open-standards/jouletable/SPEC.md

# Joule Table — A Metered, Gated, Attested Agent at Every Surface

**Version:** 0.1.0-draft.1 · **Status:** Draft · **Profile:** `jouletable/1`
**Home:** `jt.transaction.science` · **Spec text:** CC-BY-4.0 · **Reference code:** Apache-2.0

Joule Table is the open standard for **binding an accountable agent into any surface
where work happens** — a coding editor, a chat channel, a git forge, a video meeting,
a phone call. Wherever the agent shows up, the same three things hold: its authority is
a **signed grant** decided outside the model, its work is **energy-metered**, and every
action seals to a **verifiable receipt**. An agent's accountability shouldn't stop at
the edge of one tool; Joule Table is the guarantee that it doesn't.

The name is the idea: the agent takes a **seat at the table** — present where the work
is, and answerable for what it does there.

Joule Table is one of the [Transaction Science open standards](../README.md), and it
**composes** the others rather than re-implementing them: **JCP** decides and grants,
**Mesh** meters at the model front door, **`jcp-efficiency`** is the receipt, and
**Sandbox** attests execution.

---

## §1 Why Joule Table exists

The accountable-agent stack is being built one surface at a time — a hook in the editor
here, a teammate in the chat there, a bot in the meeting. Each re-answers the same three
questions (*what may it do? what did it cost? can I verify it?*) in a different, usually
un-portable way. Joule Table names the **shared substrate** those answers share, so an
agent that is metered, gated, and attested in your IDE is the same, verifiably, when it
joins your standup — and the receipts chain across both.

## §2 The three seams (the substrate every binding provides)

Every Joule Table binding, on every surface, provides the same three seams:

- **Gate** — each action is decided **outside the model** against a JCP capability +
  joule-budget grant. A capability the grant does not hold is denied before the side
  effect, whoever asked and however it was phrased.
- **Meter** — the work is measured at the **model-call boundary** (a proxy for a
  request/response model; a relay for a streaming one), in joules derived at honest
  provenance, never claimed as a physical measurement.
- **Receipt** — every decision and every completed unit seals to a **verifiable ledger**
  (`efficiency/1` + decision receipts), non-repudiable and independently checkable.

A binding is *conformant* when it provides the seams that surface allows and seals
honest receipts (§5). What differs per surface is only *how* the seams attach.

## §3 The two bindings

Joule Table has two reference bindings — one for where you *build*, one for where you
*collaborate* — and they compose.

### Joule Hook — the tool/editor binding ([`../joulehook`](../joulehook))

Carries the three seams into a **coding editor or agent host** through its own extension
points: the `PreToolUse`-hook family (Claude Code, Cursor, Windsurf, Antigravity), a
`base_url` metering proxy, an MCP receipt server. The agent works *in your tools*, gated
and metered, without forking any of them.

### Joule Desk — the collaboration/teammate binding ([`../jouledesk`](../jouledesk))

The persistent `@joule` you delegate to on a **shared surface** — a chat channel, a git
forge, or a live meeting. Its authority is a signed grant (not admin config), its every
action seals to a ledger the whole channel can verify. Binding classes: `chat`
(Slack/Discord/Matrix), `forge` (GitHub/GitLab), and `room` (the real-time class:
Zoom/Teams/Meet/LiveKit). **When Joule Desk works inside an editor, its `editor` class
*is* Joule Hook** — the two bindings meet there.

## §4 Composition

Joule Table is a through-line, not a re-implementation:

| Seam | Composed from |
|---|---|
| Gate | **JCP** — capability ⊗ joule-budget = one signed grant, decided outside the model |
| Meter | **Mesh** / `jcp-efficiency` — µJ per accepted token, per completed unit, waste |
| Receipt | `jcp-receipt` / `jcp-efficiency` — sealed, hash-verifiable JCR-1 |
| Attestation | **Sandbox** — the admitted work runs attested (`sandbox-tee::energy`) |

Joule Hook and Joule Desk each assemble these into a binding for their surface family;
Joule Table is the contract that both satisfy.

## §5 Conformance

A Joule Table binding declares which seams it provides and MUST:

1. **Decide outside the model.** No gate may consult the LLM to authorize an action.
2. **Meter at the model-call boundary** where it can reach it, at **honest provenance**
   — a binding that presents an energy figure it cannot back is non-conformant (§`jcp-efficiency`).
3. **Seal verifiable receipts** — every allow, deny, and completed unit, checkable by a
   third party holding the steward key.

A binding that can reach fewer seams on a closed surface MUST say so, not overclaim.
Joule Hook and Joule Desk are the reference bindings; new surfaces conform by providing
the same three seams.

## §6 The map

```
                         Joule Table  ·  jt.transaction.science
                    (gate · meter · receipt — at every surface)
                                    │
              ┌─────────────────────┴─────────────────────┐
        Joule Hook                                     Joule Desk
     tool / editor binding                     collaboration / teammate binding
   Claude Code · Cursor ·                     chat  (Slack · Discord · Matrix)
   Windsurf · Antigravity · Zed               forge (GitHub · GitLab)
                                               room  (Zoom · Teams · Meet · LiveKit)
              └──────────── editor class = Joule Hook ────────────┘
```

Transaction Science is the steward, not the proprietor: the seam contract and the right
to fork are public.