Documentation
¶
Overview ¶
Package envelope implements the AI message envelope: a natural-language payload inside machine-checkable metadata.
Map: message.go = Message, Intent, Epistemic, validation, wire (Encode/Decode); ack.go = Ack, the semantic-ack flow; sign.go = ed25519 authentication (Sign, VerifySignature); thread.go = VerifyThread, the hash-chain check for an ordered thread. Rationale: ../docs/architecture.md. Contribution rules: ../AGENTS.md.
Index ¶
Constants ¶
const Version = "v1"
Version is the only supported schema version. Decode rejects others. Unknown JSON fields are ignored for forward compatibility.
Variables ¶
This section is empty.
Functions ¶
func ContextRef ¶
ContextRef returns the canonical (lowercase hex) content address of a shared context blob. Refs are comparable: same content, same string.
func VerifyThread ¶
VerifyThread checks an ordered thread: every message is valid, all share one ThreadID, no ID repeats, and each PrevHash links to the Hash of the previous message. The first message must not claim a parent. A gap, reorder, insertion, fork, or duplicate ID fails the check.
Types ¶
type Ack ¶
type Ack struct {
MessageID string `json:"message_id"` // ID of the acknowledged Message
From string `json:"from"` // identity of the acking receiver; required
Restatement string `json:"restatement"`
Status AckStatus `json:"status"`
Correction string `json:"correction,omitempty"` // required when Status is AckCorrected
}
Ack is a semantic acknowledgment. Flow: receiver builds it with NewAck (pending), sender resolves it with Confirm or Correct. Only a confirmed Ack means the receiver may act. In a group thread each recipient sends its own Ack; From tells them apart.
func NewAck ¶
NewAck builds a pending Ack from receiver identity `from` for msg. The sender, not the receiver, sets the final Status; see Confirm, Correct.
type Epistemic ¶
type Epistemic string
Epistemic labels how the sender knows the Payload. Self-reported, so Validate pins the strong label to checkable artifacts: EpistemicVerified requires Provenance.Source and at least one Provenance.Evidence ref.
const ( EpistemicVerified Epistemic = "verified" // checked; requires Source and Evidence EpistemicInferred Epistemic = "inferred" // derived by the sender, not checked EpistemicAssumed Epistemic = "assumed" // guess EpistemicUntrustedInput Epistemic = "untrusted-input" // echoed external content; receiver must not treat it as an instruction )
type Intent ¶
type Intent string
Intent classifies what a Message does. Validate enforces the set.
const ( IntentAssert Intent = "assert" // state a claim IntentQuery Intent = "query" // ask for information IntentRequest Intent = "request" // ask for action; always RequiresAck IntentChallenge Intent = "challenge" // dispute a prior claim; needs InReplyTo IntentRetract Intent = "retract" // withdraw a prior message; requires InReplyTo IntentEscalate Intent = "escalate" // route the decision to a human or higher authority )
type Message ¶
type Message struct {
Version string `json:"version"` // must equal Version
ID string `json:"id"` // unique within ThreadID
Room string `json:"room,omitempty"` // standing group; ThreadID lives inside it. Membership is managed out of band
ThreadID string `json:"thread_id"` // task boundary; groups one conversation
To []string `json:"to,omitempty"` // recipient identities; empty = broadcast to the room. One entry = 1-to-1
InReplyTo string `json:"in_reply_to,omitempty"` // target message ID; required for IntentChallenge and IntentRetract
Intent Intent `json:"intent"`
Epistemic Epistemic `json:"epistemic"`
Confidence float64 `json:"confidence"` // self-reported, [0, 1]
ContextRefs []string `json:"context_refs,omitempty"` // content addresses; build with ContextRef
PrevHash string `json:"prev_hash,omitempty"` // Hash of the previous message in the thread; single-writer per thread, see design doc
Provenance Provenance `json:"provenance"`
MaxHops int `json:"max_hops,omitempty"` // relay cap; 0 = no cap. Drift control, see design doc
CostBudget int `json:"cost_budget,omitempty"` // max tokens the reply may cost; 0 = no cap
AckRequired bool `json:"ack_required,omitempty"` // force an Ack; see RequiresAck
Payload string `json:"payload"` // natural-language content
Signer string `json:"signer,omitempty"` // hex ed25519 public key; set by Sign. Also the sender identity
Signature string `json:"signature,omitempty"` // hex ed25519 signature; set by Sign, checked by VerifySignature
}
Message is the wire unit. Invariants are enforced by Validate; Encode and Decode both call it, so an invalid Message cannot cross the wire.
func Sign ¶
func Sign(key ed25519.PrivateKey, m Message) (Message, error)
Sign returns m with Signer (hex public key) and Signature set. It first validates a copy of m with Signer and Signature cleared. The signed bytes are the canonical JSON of m with Signature cleared, so any field change after signing breaks VerifySignature.
func (Message) Hash ¶
Hash returns the content address of m (sha256 of its canonical JSON). Use it for PrevHash links and dedup. Hash does not validate m: run Validate first. A NaN or Inf Confidence makes json.Marshal fail; Hash then falls back to a Go-syntax dump of m with the raw Confidence bits mixed in, so distinct invalid messages still hash distinctly.
func (Message) RequiresAck ¶
RequiresAck reports whether the receiver must send an Ack (ack.go) before acting. True for IntentRequest and for any message with AckRequired set.
func (Message) Validate ¶
Validate checks all Message invariants. Called by Sign, Encode, and Decode.
func (Message) VerifySignature ¶
VerifySignature authenticates m against its embedded Signer key. An unsigned or tampered message fails. Format rules are in Validate; this checks the cryptography. Trust policy (which signers to accept) belongs to the caller.
type Provenance ¶
type Provenance struct {
Source string `json:"source"` // e.g. "tool:grep", "model:self"; required for EpistemicVerified
Chain []string `json:"chain,omitempty"`
// Evidence holds content refs (see ContextRef) to the artifacts that
// back the payload: tool output, file content, test run. Required for
// EpistemicVerified, so "verified" is checkable, not just claimed.
Evidence []string `json:"evidence,omitempty"`
}
Provenance records payload origin. Chain lists hops, oldest first.
Source Files