Skip to content
bucker

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.

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:read on the project. Scan class bounded; 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.untrustedFields with its class. An id the scan altered is not echoed; a stable quarantined:<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