# Sense

The **ambient context** standard — the always-on, deterministic, energy-accounted
record of *what is happening around an agent*, and a principled account of *when
that is worth attention*.

The tool protocols (MCP, A2A, ACP) standardized the **efferent** half of an agent:
reaching out for tools, peers, payments. Sense standardizes the **afferent** half
— the observations flowing in. It is the substrate an *ambient* or *proactive*
agent needs but none of them specify: a feed of the world, deterministic enough to
audit, with a governed decision about when to interrupt a human.

Where OpenTelemetry traces the agent's own reasoning — non-deterministic by its
own admission, and about the agent's *insides* — Sense records the agent's
*outside*, deterministically, with every datum provenance- and trust-tagged, and
every interruption priced in joules and sealed in a receipt.

## The four tiers

```
observe ─▶ project ─▶ detect ─▶ gate ─▶ seal ─▶ verify ─▶ answer
  │           │          │        │       │        │         │
 store     attention  attention attention receipt receipt  cascade
```

- **`sense-schema`** — the wire types: the content-addressed [`Event`], the
  vendor-neutral `SourceClass`, the `TrustLevel`, the family `Energy`/`Provenance`
  model, the `StateProjection`, the `Highlight`. Pure, no IO.
- **`sense-store`** — a content-addressed, HLC-ordered, **replay-deterministic**
  event log. Two runs over the same events yield a byte-identical digest.
- **`sense-attention`** — the part no observability stack carries: a deterministic
  salience/novelty/uncertainty observer, a *k*-sigma highlight detector, and the
  **attention budget** that gates surfacing by *value vs. interruption cost*,
  priced in joules. "Perception ⊗ attention-budget", the afferent dual of JCP's
  "capability ⊗ joule-budget".
- **`sense-cascade`** — the synthesis tier: a query envelope, deterministic recall
  retrieval, and a speculative cascade that answers factual-recall queries with
  **zero LLM calls** and escalates to a frontier model only as a last resort.
- **`sense-receipt`** — a hash-chained, Ed25519-signed **surfacing log**: the
  tamper-evident record of what was surfaced (or held), when, and what it cost.
  Sealable as a JCR-1 COSE_Sign1 envelope for cross-family verification.

See [`SPEC.md`](SPEC.md) for the normative standard and
[`conformance/v1/`](conformance/v1/) for the reproducible vector pack.

## Try it

```sh
cd sense-rs
cargo run -p sense-cli --bin sense     # the whole loop on a scripted stream
cargo test --workspace                 # the conformance suite
```

The demo scripts an ambient stream (a quiet shell baseline, a burst of file
changes, a low-trust log line), then for each surfaced moment prints the
projection, the gate decision, and the joules it cost — then verifies the
hash-chained surfacing log and answers a recall query with no model call.

## What is **not** here

- **A daemon, sensors, or a UI.** A host wires its platform's sensors to the
  `SourceClass` vocabulary and renders highlights however it likes. Sense fixes the
  datum, the determinism, the attention decision, and the receipt — not the
  plumbing.
- **A model.** The salience observer and the synthesis fallback are *recognized
  edges*; the reference observer is deterministic and the reference fallback is a
  recorder. A host brings the model it trusts.
- **A transport or storage engine.** The wire is `serde`/JCR-1; the order is the
  HLC. Ride it over anything; persist it in anything that preserves the order.

## Licence

Specification text: CC-BY-4.0 ([`LICENSE-SPEC`](LICENSE-SPEC)). Reference
implementation in `sense-rs/`: Apache-2.0 ([`LICENSE`](LICENSE)).