Essence v3 and evidence packs
The Error Essence (error-essence.md) is the published 500-token document an agent reads about an issue. Essence v3 is the same idea for everything else a person can link to: an issue, a release, an alert event, a replayed session, a service, a feature flag or a host, on one skeleton, always at most 500 tokens. A companion read, the evidence pack, answers "I have N tokens; what should I read?"
Paste the link you are looking at into any agent. It calls essence_get with it and gets the view
you have, priced.
The skeleton
Every kind returns the same fields:
| Field | What it is |
|---|---|
kind, id |
What it is and how to address it. |
identity |
Title, an optional detail line, the org and project, and the dashboard address. |
state |
A verdict (failing, degraded, healthy, inactive, unknown) and at most three reasons. |
changes |
Up to three things that changed before it, with when. |
handles |
The reads that go deeper: tool, exact arguments, price in tokens, scan class. |
notChecked |
What Bucker did not look at, so silence is never read as health. |
freshness |
The newest datum the verdict reflects, when it was generated, and how it was measured. |
emptiness |
Present when nothing is behind it: why (not_ingested, no_data_in_window, ...) and what to read next. |
The verdict is unknown, never healthy, for an entity with nothing behind it.
What each verdict means, by kind
| Kind | Reads | failing |
degraded |
healthy |
|---|---|---|---|---|
| issue | the issue, its cached essence | open, error or fatal, seen within the hour | open and quiet, or not severe | not used: an open issue is never healthy; resolved or archived is inactive |
| release | health rollups, deploys, commits | under 95% crash-free sessions in 24 h | under 99% | 99% or better; no sessions is unknown |
| alert event | the event, its rule, its issue | delivery failed or dead, or the linked issue is still active | queued or pending | delivered; suppressed is inactive |
| session | replay segments (counts only) | errors with rage clicks or failed requests | errors, rage clicks, failed or console errors | none of those |
| service | server request rollups, 24 h | 5% or more of requests errored | 1% or more | under 1%; no traffic is unknown |
| flag | the flag, its lifecycle, debt, changes | not used | ghost, orphan, expired, in debt, or changed within the hour | otherwise; archived is inactive |
| host | infrastructure entity and its coverage | not used | seen within a day but not within 15 minutes, or reporting no signal | seen within 15 minutes and at least one live signal; silent for a day is unknown |
Funnel step is named and reserved. It is end-user analytics, behind the per-project PA-01 gate, so
it answers not_available until that ships. The session essence reads replay segment counts only:
no identity, no event content.
One read for any link: essence_get
essence_get { url: "https://app.bucker.io/en/org/acme/web/issues/WEB-42" }
essence_get { url: "release:2.14.3", org: "acme", project: "web" }
Links on this deployment's dashboard host (or app.bucker.io) are read; anything else is not a
link to an object. A reference is kind:id with the org and project. The dashboard's address for
each kind:
| Kind | Address |
|---|---|
| issue | /<locale>/org/<org>/<project>/issues/<id or short id> |
| release | /org/<org>/<project>/releases/<version> |
| session | /org/<org>/<project>/replays/<replay id> |
| service | /org/<org>/<project>/infra?service=<name> |
| host | /org/<org>/<project>/infra?host=<identity> |
| flag | /org/<org>/<project>/flags?flag=<key> |
| alert event | /org/<org>/<project>/alerts?event=<id> |
A link the token cannot read answers exactly as a link to nothing. An org that does not exist,
another organization's project, a project the token has no event:read on, an entity in a sibling
project, a link on another host and text that is not a link all return the same 404, decided
before any row of the entity is read. Existence is not learned from a link. A host also needs
infra:read; a token without it sees a host as missing.
One read for any budget: evidence_pack_get
evidence_pack_get { url: "issue:WEB-42", org: "acme", project: "web", budget: 4000 }
The budget is 400 to 32,000 tokens (default 4,000). The pack chooses among seven blocks: the essence, the stack frames, a trace slice, a log window, the replay transcript, the change events and the flag exposure. The essence and a longer change-event list are carried inline; the others are priced reads with the exact arguments to call them with. Blocks come back ordered by value per token, and what was left out is listed with the price and value it left.
The budget is exact. spentTokens is the whole pack counted as every envelope is counted,
plus the price of each read it recommends. It never exceeds the budget; the tool reserves its own
trust block out of it.
Value is never a model's. For an issue whose class has history (at least five served
essences), a block is worth the share of served essences that were followed by a pull of that
block's read, plus the outcome gain the field ablation measured for the field behind it
(basis: measured). Otherwise it is a published prior (basis: prior), the plain table
PACK_PRIORS in essence-v3-schema.ts. A figure is one or the other, never blended. Selection
is an exact knapsack over integer token prices: the set with the highest total value that fits,
and among equal values, the cheaper one.
packId is a hash of the org, project, subject, chosen blocks and budget. An approval card can
recompute it to show what the agent was given. Nothing is stored.
Safety
- Reads, under
event:readon the project. Scan classbounded; charged to tokens. - Everything a customer wrote (title, detail, change summaries, a customer-chosen id or handle
argument) is scrubbed with the org's rules and scanned for instructions, and every path that
holds one is named in
trust.untrustedFieldswith its class. An id the scan altered is not echoed; a stablequarantined:<digest>stands in for it. - A handle is offered only if the entity carries the key it needs, the caller holds its relation, and, for an issue's hydration reads, the cached essence counted something behind it.
- An incident-bound credential reads nothing here; the issue's own essence is
issue_essence.
REST
The dashboard's "agent view" and "what an agent is given" read the same answers:
GET /orgs/:org/projects/:project/essence/:kind/:id
GET /orgs/:org/projects/:project/essence-by-url?url=...
GET /orgs/:org/projects/:project/evidence-pack/:kind/:id?budget=4000