metered-protocol 1.0.0

package/dist/src/http/serve.js

@@ -0,0 +1,171 @@
+/**
+ * The HTTP glue. Thin on purpose: every rule lives in provider.ts and service.ts, and this only
+ * maps them onto requests and status codes.
+ *
+ * ROUTING IS BY sessionId, AND IT COSTS NOTHING EXTRA. Every message in SPEC.md 3 already carries
+ * one, because the specification needed it to stop a Reservation or Measurement being lifted from
+ * one session into another -- threat X1. A field that exists for a security reason turns
+ * out to be exactly the routing key a multi-session server needs, so there is no session cookie,
+ * no header, and no server-side handle to leak or confuse.
+ *
+ * An unpaid request gets x402's 402 with the signed Offer in `accepts`. A client that speaks x402
+ * but not this scheme reads the envelope, sees `scheme: "metered"` and declines cleanly.
+ */
+import { createServer } from 'node:http';
+import { digestHex, verifyState } from '../encoding.js';
+import { SessionRejected } from './provider.js';
+import { ReservationUnauthenticated } from '../reservation.js';
+import { toPaymentRequired, errorBody, toBase64 } from './protocol.js';
+/**
+ * The largest request this server will read. A Reservation, a Measurement and a State are all a
+ * few hundred bytes; a prompt is the only field with any size to it.
+ *
+ * BOUNDED ON PURPOSE. Reading an unbounded body means an unauthenticated client can hold the
+ * process open and grow a buffer until it dies -- which costs the attacker nothing and does not
+ * require knowing any session. This is the cheapest denial of service there is, and the only
+ * defence is to refuse to read past a limit.
+ */
+export const MAX_BODY_BYTES = 256 * 1024;
+export class BodyTooLarge extends Error {
+}
+async function readJson(req) {
+    // Cheapest refusal first: a declared length over the cap needs no reading at all.
+    const declared = Number(req.headers['content-length'] ?? NaN);
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        throw new BodyTooLarge(`declared body of ${declared} bytes exceeds ${MAX_BODY_BYTES}`);
+    }
+    const parts = [];
+    let size = 0;
+    let over = false;
+    for await (const c of req) {
+        const buf = c;
+        size += buf.length;
+        if (size > MAX_BODY_BYTES) {
+            // STOP BUFFERING, KEEP DRAINING. Destroying the socket here loses the response: the client
+            // sees a dropped connection rather than a refusal, and cannot tell a limit from a crash.
+            // Memory stays bounded because nothing further is kept.
+            over = true;
+            parts.length = 0;
+            continue;
+        }
+        parts.push(buf);
+    }
+    if (over)
+        throw new BodyTooLarge(`request body exceeds ${MAX_BODY_BYTES} bytes`);
+    return JSON.parse(Buffer.concat(parts).toString('utf8'));
+}
+const NO_SESSION = ['no such session', 'unknown, halted or evicted'];
+async function handleOpen(svc, req, reply, resource) {
+    const body = await readJson(req);
+    if (!body.buyerPubkey)
+        return reply(400, errorBody('open requires buyerPubkey'));
+    // The 402 IS the answer here, not an error: it carries the terms.
+    return reply(402, toPaymentRequired(svc.open(body.buyerPubkey), resource, 'metered session available'));
+}
+/**
+ * ONLY AN AUTHENTICATED COUNTERPARTY MAY HALT A SESSION.
+ *
+ * SPEC.md 1's "the only remedy for disagreement is to stop" is about two parties who have
+ * authenticated themselves and cannot agree on a measurement. It is NOT about a malformed message
+ * from an unknown sender -- and `sessionId` is not a secret, it is carried in clear in every
+ * message on the wire. Halting on any failure meant anyone who could observe a session id could
+ * permanently kill that session with one junk request, which is a denial of service wearing the
+ * specification as a disguise.
+ *
+ * So a failure to AUTHENTICATE is answered with a refusal and no change of state; a failure to
+ * AGREE, which only an authenticated party can reach, halts.
+ */
+const isUnauthenticated = (err) => err instanceof ReservationUnauthenticated || err instanceof BodyTooLarge || err instanceof SyntaxError;
+async function handleBabel(svc, req, reply) {
+    const body = await readJson(req);
+    const id = body.reservation?.sessionId;
+    const session = id ? svc.get(id) : undefined;
+    if (!session || !id)
+        return reply(404, errorBody(...NO_SESSION));
+    try {
+        const { content, measurement } = session.chunk(body.reservation, body.prompt);
+        svc.persist(id);
+        return reply(200, { contentB64: toBase64(content), measurement });
+    }
+    catch (err) {
+        if (isUnauthenticated(err))
+            return reply(403, errorBody('rejected', String(err)));
+        svc.halt(id);
+        throw err;
+    }
+}
+async function handleState(svc, req, reply) {
+    const body = await readJson(req);
+    const id = body.measurement?.sessionId;
+    const session = id ? svc.get(id) : undefined;
+    if (!session || !id)
+        return reply(404, errorBody(...NO_SESSION));
+    try {
+        const settled = session.settle(body.measurement);
+        svc.persist(id);
+        return reply(200, settled);
+    }
+    catch (err) {
+        if (isUnauthenticated(err))
+            return reply(403, errorBody('rejected', String(err)));
+        // A disagreement stops the session for good, not just this request (SPEC.md 1).
+        svc.halt(id);
+        throw err;
+    }
+}
+async function handleCountersign(svc, req, reply) {
+    const body = await readJson(req);
+    const id = body.state?.sessionId;
+    const session = id ? svc.get(id) : undefined;
+    const offer = id ? svc.offerFor(id) : undefined;
+    if (!session || !offer || !id)
+        return reply(404, errorBody(...NO_SESSION));
+    if (!verifyState(body.state, body.buyerSig, offer.buyerPubkey)) {
+        // NOT a halt. An unverifiable signature means the sender is not the buyer, so this message is
+        // evidence about the sender and none at all about the session. See isUnauthenticated above.
+        return reply(403, errorBody('the buyer signature does not verify'));
+    }
+    session.chainTo(digestHex(body.state));
+    svc.persist(id);
+    return reply(200, { chained: digestHex(body.state) });
+}
+const ROUTES = {
+    '/metered/open': handleOpen,
+    '/metered/babel': (s, r, reply) => handleBabel(s, r, reply),
+    '/metered/state': (s, r, reply) => handleState(s, r, reply),
+    '/metered/countersign': (s, r, reply) => handleCountersign(s, r, reply),
+};
+export function meteredHandler(opts) {
+    const resource = opts.resource ?? '/metered';
+    return async (req, res) => {
+        const reply = (code, body) => {
+            const payload = JSON.stringify(body);
+            res.writeHead(code, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) });
+            res.end(payload);
+        };
+        try {
+            if (req.method !== 'POST')
+                return reply(405, errorBody('POST only'));
+            const route = ROUTES[req.url ?? ''];
+            if (!route)
+                return reply(404, errorBody('no such endpoint'));
+            await route(opts.service, req, reply, resource);
+        }
+        catch (err) {
+            if (err instanceof SessionRejected) {
+                // 409: the session cannot continue. SPEC.md 1 -- the only remedy for disagreement is to stop.
+                return reply(409, errorBody('session halted', err.message));
+            }
+            if (err instanceof BodyTooLarge)
+                return reply(413, errorBody('request too large', err.message));
+            return reply(400, errorBody('bad request', err instanceof Error ? err.message : String(err)));
+        }
+    };
+}
+export function serveMetered(opts) {
+    const handler = meteredHandler(opts);
+    return createServer((req, res) => {
+        void handler(req, res);
+    });
+}
+//# sourceMappingURL=serve.js.map

package/dist/src/http/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../../src/http/serve.ts"],"names":[],"mappings":"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"}

package/dist/src/http/service.d.ts

@@ -0,0 +1,86 @@
+import { ProviderSession, type Deliver, type Meter } from './provider.js';
+import { Checkpointer, type Anchor } from '../checkpoint.js';
+import { type SignerStore } from '../signer.js';
+import type { SessionStore } from '../store.js';
+import type { Offer } from '../types.js';
+/** Everything about an Offer except who the buyer is, which is not known until one asks. */
+export type OfferTerms = Omit<Offer, 'sessionId' | 'buyerPubkey' | 'partiesCommitment' | 'sig' | 'providerPubkey'>;
+export interface ServiceOptions {
+    terms: OfferTerms;
+    providerSk: string;
+    providerPubkey: string;
+    meter: Meter;
+    deliver: Deliver;
+    /** How many sessions to keep. The oldest is evicted past this, halted ones first. */
+    maxSessions?: number | undefined;
+    /**
+     * SPEC.md 8. Each session gets its OWN Checkpointer over this one anchor, so a session's
+     * checkpoint records stay with the session and are evicted with it.
+     */
+    anchor?: Anchor | undefined;
+    /**
+     * SPEC.md 4. Shared across sessions deliberately: SignerRecord is keyed by sessionId, so one
+     * store holds every session this provider has ever signed for -- which is exactly what 4.4's
+     * restart rule needs to consult. Defaults to memory; src/store.ts survives a restart.
+     */
+    store?: SignerStore | undefined;
+    /**
+     * SPEC.md has nothing to say about this: it is an implementation quality. Without it a restart
+     * forgets what has been OFFERED and every buyer opens again, losing at most the babel in
+     * flight. With it, a buyer does not notice.
+     */
+    sessions?: SessionStore | undefined;
+}
+export declare class MeteredService {
+    private readonly opts;
+    private readonly sessions;
+    /** One store for every session, because SPEC.md 4.4 asks what this PARTY has signed. */
+    private readonly store;
+    constructor(opts: ServiceOptions);
+    get size(): number;
+    /** Mint a session for one buyer and return its signed Offer. */
+    open(buyerPubkey: string): Offer;
+    /**
+     * The session for an id, or undefined. Callers turn undefined into a 404, not a crash.
+     *
+     * REHYDRATES on a miss when a durable session store is configured, so a buyer whose provider
+     * restarted mid-session carries on rather than starting again.
+     */
+    get(sessionId: string): ProviderSession | undefined;
+    /** Rebuild a session from the durable store, if one is configured and holds it. */
+    private rehydrate;
+    /**
+     * Write a session down after it has moved. Called by the handlers, because only they know a
+     * message was accepted -- persisting before that would record a state nobody agreed to.
+     */
+    persist(sessionId: string): void;
+    offerFor(sessionId: string): Offer | undefined;
+    /** A session's checkpoint records, for an operator asking what has been anchored. */
+    checkpointsFor(sessionId: string): ReturnType<Checkpointer['all']>;
+    /**
+     * Wait for a finished session's anchors to land, so a REPORT can say what became of them.
+     * Never call this while a session is running -- see Checkpointer.settled.
+     */
+    checkpointsSettled(sessionId: string): Promise<void>;
+    /**
+     * Mark a session dead. SPEC.md 1: "the only remedy for disagreement is to stop", and stopping
+     * has to be sticky -- a halted session that answers the next request has not stopped.
+     */
+    halt(sessionId: string): void;
+    isHalted(sessionId: string): boolean;
+    /** Keep the map bounded: halted sessions go first, then the oldest. */
+    /**
+     * Keep the session map bounded, dropping the least valuable first.
+     *
+     * ORDER MATTERS UNDER ATTACK, and the obvious order is the wrong one. Opening a session is free
+     * and unauthenticated -- anyone may ask for terms -- so an attacker can open sessions as fast as
+     * it likes. Evicting purely by age hands it a weapon: its fresh sessions survive while real
+     * buyers, who are older by definition, get dropped mid-session.
+     *
+     * So progress is what is protected. Halted sessions go first, then sessions that have never
+     * delivered a babel -- which is exactly what a flood consists of -- and only then the oldest.
+     * A buyer partway through a session is the last thing to be thrown away.
+     */
+    private evict;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/src/http/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/http/service.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,eAAe,EAAE,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,4FAA4F;AAC5F,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,GAAG,mBAAmB,GAAG,KAAK,GAAG,gBAAgB,CAAC,CAAC;AAEnH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CACrC;AAUD,qBAAa,cAAc;IAMb,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,wFAAwF;IACxF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBAEP,IAAI,EAAE,cAAc;IAIjD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gEAAgE;IAChE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,KAAK;IA+BhC;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAMnD,mFAAmF;IACnF,OAAO,CAAC,SAAS;IAiBjB;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKhC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAI9C,qFAAqF;IACrF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IAIlE;;;OAGG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D;;;OAGG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAO7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIpC,uEAAuE;IACvE;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,KAAK;CAcd"}

package/dist/src/http/service.js

@@ -0,0 +1,161 @@
+/**
+ * Many sessions at once, which is the difference between a demo and a server.
+ *
+ * WHY `/open` TAKES THE BUYER'S KEY. An Offer names `buyerPubkey` and commits to
+ * `blake3(buyer || provider)`, so it cannot be signed until the provider knows who is asking.
+ * The single-session version dodged this by having the Offer pre-made with both keys baked in,
+ * which quietly meant a server could only ever serve one buyer. Asking for the key at open is
+ * what makes the commitment honest AND makes many sessions possible; the two were the same
+ * problem.
+ *
+ * WHAT PERSISTS AND WHAT DOES NOT. Sessions live in memory, so a restart forgets what has been
+ * OFFERED and every buyer must open again. That is survivable because a Reservation authorises
+ * ONE chunk -- the most anyone loses to a forgotten session is that chunk.
+ *
+ * What has been SIGNED is a different matter, and forgetting it loses money. SPEC.md 4 is carried
+ * by a SignerStore threaded through every session here. Until 2026-09-10 it was not: src/signer.ts
+ * implemented all four obligations, src/session.ts used them, and NOTHING ELSE DID -- this server
+ * called `signState` directly, so the rules that exist to stop a party signing two States at one
+ * seq were running only in session.ts's own test. Passing a store from src/store.ts is what makes
+ * 4.4's restart rule true rather than available.
+ */
+import { randomBytes } from 'node:crypto';
+import { bytesToHex } from '@noble/hashes/utils';
+import { signEnvelope, partiesCommitment } from '../encoding.js';
+import { ProviderSession } from './provider.js';
+import { Checkpointer } from '../checkpoint.js';
+import { memoryStore } from '../signer.js';
+export class MeteredService {
+    opts;
+    sessions = new Map();
+    /** One store for every session, because SPEC.md 4.4 asks what this PARTY has signed. */
+    store;
+    constructor(opts) {
+        this.opts = opts;
+        this.store = opts.store ?? memoryStore();
+    }
+    get size() {
+        return this.sessions.size;
+    }
+    /** Mint a session for one buyer and return its signed Offer. */
+    open(buyerPubkey) {
+        if (!/^[0-9a-f]{64}$/i.test(buyerPubkey))
+            throw new Error('buyerPubkey must be 32 hex bytes');
+        this.evict();
+        const sessionId = bytesToHex(randomBytes(16)); // SPEC.md 3.1: 16 bytes
+        const parties = partiesCommitment(buyerPubkey, this.opts.providerPubkey);
+        const offer = signEnvelope({
+            ...this.opts.terms,
+            sessionId,
+            buyerPubkey: buyerPubkey.toLowerCase(),
+            providerPubkey: this.opts.providerPubkey,
+            partiesCommitment: parties,
+        }, this.opts.providerSk);
+        const checkpointer = this.opts.anchor ? new Checkpointer(this.opts.anchor) : undefined;
+        this.sessions.set(sessionId, {
+            offer,
+            session: new ProviderSession(offer, this.opts.providerSk, this.opts.meter, this.opts.deliver, checkpointer, this.store),
+            checkpointer,
+            opened: Date.now(),
+            halted: false,
+        });
+        this.persist(sessionId);
+        return offer;
+    }
+    /**
+     * The session for an id, or undefined. Callers turn undefined into a 404, not a crash.
+     *
+     * REHYDRATES on a miss when a durable session store is configured, so a buyer whose provider
+     * restarted mid-session carries on rather than starting again.
+     */
+    get(sessionId) {
+        const entry = this.sessions.get(sessionId) ?? this.rehydrate(sessionId);
+        if (!entry || entry.halted)
+            return undefined;
+        return entry.session;
+    }
+    /** Rebuild a session from the durable store, if one is configured and holds it. */
+    rehydrate(sessionId) {
+        const snapshot = this.opts.sessions?.load(sessionId);
+        if (!snapshot)
+            return undefined;
+        const checkpointer = this.opts.anchor ? new Checkpointer(this.opts.anchor) : undefined;
+        const entry = {
+            offer: snapshot.offer,
+            session: ProviderSession.restore(snapshot, this.opts.providerSk, this.opts.meter, this.opts.deliver, checkpointer, this.store),
+            checkpointer,
+            opened: Date.now(),
+            halted: false,
+        };
+        this.sessions.set(sessionId, entry);
+        return entry;
+    }
+    /**
+     * Write a session down after it has moved. Called by the handlers, because only they know a
+     * message was accepted -- persisting before that would record a state nobody agreed to.
+     */
+    persist(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (entry && this.opts.sessions)
+            this.opts.sessions.save(entry.session.snapshot());
+    }
+    offerFor(sessionId) {
+        return this.sessions.get(sessionId)?.offer;
+    }
+    /** A session's checkpoint records, for an operator asking what has been anchored. */
+    checkpointsFor(sessionId) {
+        return this.sessions.get(sessionId)?.checkpointer?.all() ?? [];
+    }
+    /**
+     * Wait for a finished session's anchors to land, so a REPORT can say what became of them.
+     * Never call this while a session is running -- see Checkpointer.settled.
+     */
+    async checkpointsSettled(sessionId) {
+        await this.sessions.get(sessionId)?.checkpointer?.settled();
+    }
+    /**
+     * Mark a session dead. SPEC.md 1: "the only remedy for disagreement is to stop", and stopping
+     * has to be sticky -- a halted session that answers the next request has not stopped.
+     */
+    halt(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (entry)
+            entry.halted = true;
+        // A halt must survive a restart too, or the remedy stops working the moment a process does.
+        this.opts.sessions?.drop(sessionId);
+    }
+    isHalted(sessionId) {
+        return this.sessions.get(sessionId)?.halted ?? false;
+    }
+    /** Keep the map bounded: halted sessions go first, then the oldest. */
+    /**
+     * Keep the session map bounded, dropping the least valuable first.
+     *
+     * ORDER MATTERS UNDER ATTACK, and the obvious order is the wrong one. Opening a session is free
+     * and unauthenticated -- anyone may ask for terms -- so an attacker can open sessions as fast as
+     * it likes. Evicting purely by age hands it a weapon: its fresh sessions survive while real
+     * buyers, who are older by definition, get dropped mid-session.
+     *
+     * So progress is what is protected. Halted sessions go first, then sessions that have never
+     * delivered a babel -- which is exactly what a flood consists of -- and only then the oldest.
+     * A buyer partway through a session is the last thing to be thrown away.
+     */
+    evict() {
+        const max = this.opts.maxSessions ?? 1000;
+        if (this.sessions.size < max)
+            return;
+        const rank = (e) => {
+            if (e.halted)
+                return 0;
+            return e.session.pendingSeq < 0 ? 1 : 2;
+        };
+        const entries = [...this.sessions.entries()].sort((a, b) => {
+            const byRank = rank(a[1]) - rank(b[1]);
+            return byRank !== 0 ? byRank : a[1].opened - b[1].opened;
+        });
+        const drop = this.sessions.size - max + 1;
+        for (const [id] of entries.slice(0, drop))
+            this.sessions.delete(id);
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/src/http/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../src/http/service.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * What a program using this protocol is allowed to reach for.
+ *
+ * THIS FILE EXISTS BECAUSE SOMETHING TRIED TO USE THE PROTOCOL. Until then every import in the
+ * repository was relative and internal, so the question "what is the public surface?" had never
+ * been asked, and the honest answer was "all of it" -- which means any rearrangement inside `src/`
+ * is a breaking change for somebody.
+ *
+ * So this is the whole of what is promised. Anything not re-exported here is internal and may move
+ * without warning. Deliberately absent: the reconciliation internals, the bias detector, and the
+ * canonical encoder's private helpers.
+ *
+ * SETTLEMENT IS NOT ABSENT, IT IS ELSEWHERE -- `metered/chain`. An earlier version of this comment
+ * called the chain tooling "a demonstration of the covenant rather than part of the protocol a
+ * caller links against", and the first product built on this protocol falsified that within the
+ * day: the covenant is what makes the signed numbers enforceable, so of course a caller needs it.
+ * The split is about COST, not importance. Everything in this file is plain TypeScript over the
+ * messages; everything behind `metered/chain` needs a WASM SDK and a contract compiler, and a
+ * buyer that only speaks the protocol should not pay for those to do it.
+ *
+ * The list is short on purpose. A surface is a promise, and every name added here is one more
+ * thing that cannot be changed later without telling someone.
+ */
+/** Building and running a provider. */
+export { MeteredService, type OfferTerms, type ServiceOptions } from './http/service.js';
+export { serveMetered, meteredHandler, BodyTooLarge } from './http/serve.js';
+export { ProviderSession, SessionRejected, type Deliver, type Meter } from './http/provider.js';
+/** Being a buyer. */
+export { BuyerSession, BuyerRefused } from './http/buyer.js';
+export { openSession, runBabel, readOffer, ProtocolError, type ChunkOutcome } from './http/client.js';
+/** The wire, for anything speaking it directly rather than through the client. */
+export { toBase64, fromBase64, toPaymentRequired, X402_VERSION, type BabelResponse, type ChunkRequest, type StateRequest, type PaymentRequiredBody, } from './http/protocol.js';
+/** Units and meters (SPEC.md 6). */
+export { resolveMeter, meterFor, minimumTolerance, available, encodeWith, MeterUnavailable } from './meter.js';
+/** Durability. A provider that holds money must not forget what it has signed (SPEC.md 4). */
+export { fileStore, fileHistory, fileSessionStore, type SessionStore } from './store.js';
+export { memoryStore, SignerObligationError, type SignerStore, type SignerRecord } from './signer.js';
+export { memoryHistory, type SessionHistory } from './history.js';
+/**
+ * The types an implementable interface is made of.
+ *
+ * These are here because leaving them out made the surface LOOK complete and be unusable:
+ * `ServiceOptions` accepts an `anchor` and a `sessions` store, and neither the `Anchor` interface
+ * nor `SessionStore`'s snapshot type could be reached, so a caller could see where its own
+ * implementation was meant to go and had no way to write one. A type named in an exported
+ * signature is part of the surface whether or not anybody remembered to say so.
+ */
+export { Checkpointer, isCheckpointBabel, type Anchor, type CheckpointRecord } from './checkpoint.js';
+export type { SessionSnapshot } from './http/provider.js';
+export type { BabelCursor } from './reservation.js';
+export type { BiasState } from './bias.js';
+export { ReservationRejected, ReservationUnauthenticated, acceptReservation } from './reservation.js';
+export { MAX_BODY_BYTES, type ServeOptions } from './http/serve.js';
+export type { StateResponse, ErrorBody } from './http/protocol.js';
+/**
+ * SPEC.md 7.3a. The response window is the PROVIDER'S DEADLINE: once the covenant ages past it
+ * with no claim pending, the buyer can take back everything, including work already delivered.
+ * A provider that never asks itself when to settle will eventually deliver for free.
+ */
+export { shouldSettle, acceptPolicy, worstCaseExposure, PolicyRejected, CONFIRM_MARGIN_DAA, type ExposurePolicy, type Exposure, } from './deadline.js';
+/** Accepting an Offer, and what a session costs to fund (SPEC.md 3.1, 7.4b). */
+export { acceptOffer, OfferRejected } from './offer.js';
+export { priceOf, requiredFunding, CLOSE_FEE_SOMPI, MIN_COVENANT_SOMPI } from './reservation.js';
+/** Signing and digesting, for a caller that builds messages itself. */
+export { publicKeyHex, signEnvelope, signState, verify, verifyState, canonicalize, digestHex, blake3Hex, utf8, settlementPreimage, partiesCommitment, stateSigningPayload, settlementDigest, } from './encoding.js';
+/** The messages themselves. */
+export type { Offer, Reservation, Measurement, State, Halt, HaltReason, Reconciled } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,uCAAuC;AACvC,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhG,qBAAqB;AACrB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEtG,kFAAkF;AAClF,OAAO,EACL,QAAQ,EAAE,UAAU,EAAE,iBAAiB,EAAE,YAAY,EACrD,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,mBAAmB,GACnF,MAAM,oBAAoB,CAAC;AAE5B,oCAAoC;AACpC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,gBAAgB,EAAE,SAAS,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE/G,8FAA8F;AAC9F,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AACtG,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAElE;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,KAAK,MAAM,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACtG,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACtG,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;;GAIG;AACH,OAAO,EACL,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EACjF,KAAK,cAAc,EAAE,KAAK,QAAQ,GACnC,MAAM,eAAe,CAAC;AAEvB,gFAAgF;AAChF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEjG,uEAAuE;AACvE,OAAO,EACL,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAC1D,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,kBAAkB,EAC5D,iBAAiB,EAAE,mBAAmB,EAAE,gBAAgB,GACzD,MAAM,eAAe,CAAC;AAEvB,+BAA+B;AAC/B,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,62 @@
+/**
+ * What a program using this protocol is allowed to reach for.
+ *
+ * THIS FILE EXISTS BECAUSE SOMETHING TRIED TO USE THE PROTOCOL. Until then every import in the
+ * repository was relative and internal, so the question "what is the public surface?" had never
+ * been asked, and the honest answer was "all of it" -- which means any rearrangement inside `src/`
+ * is a breaking change for somebody.
+ *
+ * So this is the whole of what is promised. Anything not re-exported here is internal and may move
+ * without warning. Deliberately absent: the reconciliation internals, the bias detector, and the
+ * canonical encoder's private helpers.
+ *
+ * SETTLEMENT IS NOT ABSENT, IT IS ELSEWHERE -- `metered/chain`. An earlier version of this comment
+ * called the chain tooling "a demonstration of the covenant rather than part of the protocol a
+ * caller links against", and the first product built on this protocol falsified that within the
+ * day: the covenant is what makes the signed numbers enforceable, so of course a caller needs it.
+ * The split is about COST, not importance. Everything in this file is plain TypeScript over the
+ * messages; everything behind `metered/chain` needs a WASM SDK and a contract compiler, and a
+ * buyer that only speaks the protocol should not pay for those to do it.
+ *
+ * The list is short on purpose. A surface is a promise, and every name added here is one more
+ * thing that cannot be changed later without telling someone.
+ */
+/** Building and running a provider. */
+export { MeteredService } from './http/service.js';
+export { serveMetered, meteredHandler, BodyTooLarge } from './http/serve.js';
+export { ProviderSession, SessionRejected } from './http/provider.js';
+/** Being a buyer. */
+export { BuyerSession, BuyerRefused } from './http/buyer.js';
+export { openSession, runBabel, readOffer, ProtocolError } from './http/client.js';
+/** The wire, for anything speaking it directly rather than through the client. */
+export { toBase64, fromBase64, toPaymentRequired, X402_VERSION, } from './http/protocol.js';
+/** Units and meters (SPEC.md 6). */
+export { resolveMeter, meterFor, minimumTolerance, available, encodeWith, MeterUnavailable } from './meter.js';
+/** Durability. A provider that holds money must not forget what it has signed (SPEC.md 4). */
+export { fileStore, fileHistory, fileSessionStore } from './store.js';
+export { memoryStore, SignerObligationError } from './signer.js';
+export { memoryHistory } from './history.js';
+/**
+ * The types an implementable interface is made of.
+ *
+ * These are here because leaving them out made the surface LOOK complete and be unusable:
+ * `ServiceOptions` accepts an `anchor` and a `sessions` store, and neither the `Anchor` interface
+ * nor `SessionStore`'s snapshot type could be reached, so a caller could see where its own
+ * implementation was meant to go and had no way to write one. A type named in an exported
+ * signature is part of the surface whether or not anybody remembered to say so.
+ */
+export { Checkpointer, isCheckpointBabel } from './checkpoint.js';
+export { ReservationRejected, ReservationUnauthenticated, acceptReservation } from './reservation.js';
+export { MAX_BODY_BYTES } from './http/serve.js';
+/**
+ * SPEC.md 7.3a. The response window is the PROVIDER'S DEADLINE: once the covenant ages past it
+ * with no claim pending, the buyer can take back everything, including work already delivered.
+ * A provider that never asks itself when to settle will eventually deliver for free.
+ */
+export { shouldSettle, acceptPolicy, worstCaseExposure, PolicyRejected, CONFIRM_MARGIN_DAA, } from './deadline.js';
+/** Accepting an Offer, and what a session costs to fund (SPEC.md 3.1, 7.4b). */
+export { acceptOffer, OfferRejected } from './offer.js';
+export { priceOf, requiredFunding, CLOSE_FEE_SOMPI, MIN_COVENANT_SOMPI } from './reservation.js';
+/** Signing and digesting, for a caller that builds messages itself. */
+export { publicKeyHex, signEnvelope, signState, verify, verifyState, canonicalize, digestHex, blake3Hex, utf8, settlementPreimage, partiesCommitment, stateSigningPayload, settlementDigest, } from './encoding.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,uCAAuC;AACvC,OAAO,EAAE,cAAc,EAAwC,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,eAAe,EAA4B,MAAM,oBAAoB,CAAC;AAEhG,qBAAqB;AACrB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAqB,MAAM,kBAAkB,CAAC;AAEtG,kFAAkF;AAClF,OAAO,EACL,QAAQ,EAAE,UAAU,EAAE,iBAAiB,EAAE,YAAY,GAEtD,MAAM,oBAAoB,CAAC;AAE5B,oCAAoC;AACpC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,gBAAgB,EAAE,SAAS,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE/G,8FAA8F;AAC9F,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAqB,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAuC,MAAM,aAAa,CAAC;AACtG,OAAO,EAAE,aAAa,EAAuB,MAAM,cAAc,CAAC;AAElE;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAsC,MAAM,iBAAiB,CAAC;AAItG,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACtG,OAAO,EAAE,cAAc,EAAqB,MAAM,iBAAiB,CAAC;AAGpE;;;;GAIG;AACH,OAAO,EACL,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,GAElF,MAAM,eAAe,CAAC;AAEvB,gFAAgF;AAChF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEjG,uEAAuE;AACvE,OAAO,EACL,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAC1D,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,kBAAkB,EAC5D,iBAAiB,EAAE,mBAAmB,EAAE,gBAAgB,GACzD,MAAM,eAAe,CAAC"}

package/dist/src/meter.d.ts

@@ -0,0 +1,39 @@
+export declare class MeterUnavailable extends Error {
+}
+export interface Meter {
+    /** The name an Offer carries. */
+    name: string;
+    /** The unit this meter measures. An Offer naming a different unit is refused. */
+    unit: string;
+    /** Content in, units out. BYTES in: a meter measures what was delivered, and what is
+     * delivered is bytes. A meter for a text unit decodes them itself. */
+    count(content: Uint8Array): number;
+    /**
+     * Whether two correct implementations ALWAYS reach the same number for the same bytes.
+     * `true` permits `toleranceAbs` of 0; `false` requires at least 1.
+     */
+    exact: boolean;
+}
+/**
+ * The meter an Offer names, or throw.
+ *
+ * NO FALLBACK, DELIBERATELY. Counting with a meter other than the one agreed produces a number
+ * that looks like a measurement, settles like one, and is not one. §3.1 requires an Offer whose
+ * meter cannot be obtained to be refused, and this is where that refusal happens.
+ */
+export declare function resolveMeter(name: string, unit?: string): Meter;
+/**
+ * The smallest tolerance an Offer may carry for this meter.
+ *
+ * SPEC.md §3.1. An exact meter permits 0, and should use it: honest divergence is impossible, so
+ * any tolerance is pure shaving room. An inexact meter requires at least 1, because Study A
+ * measured a one-token disagreement between honest parties and a zero tolerance would halt them.
+ */
+export declare const minimumTolerance: (meter: Meter) => number;
+/** A counting function for the named meter, for callers that want only the number. */
+export declare function meterFor(name: string, unit?: string): (content: Uint8Array) => number;
+/** Token ids, for the conformance comparison that pins boundaries rather than totals. */
+export declare function encodeWith(name: string, text: string): number[];
+/** Every meter this implementation can serve, for a provider building an Offer. */
+export declare const available: () => string[];
+//# sourceMappingURL=meter.d.ts.map

package/dist/src/meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.d.ts","sourceRoot":"","sources":["../../src/meter.ts"],"names":[],"mappings":"AA6BA,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C,MAAM,WAAW,KAAK;IACpB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb;0EACsE;IACtE,KAAK,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC;IACnC;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAmCD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAc/D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,KAAK,KAAG,MAA+B,CAAC;AAEhF,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,CAAC,OAAO,EAAE,UAAU,KAAK,MAAM,CAGrF;AAED,yFAAyF;AACzF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAG/D;AAED,mFAAmF;AACnF,eAAO,MAAM,SAAS,QAAO,MAAM,EAA2B,CAAC"}