@mida-context/sdk 0.1.0

package/dist/types/api/app.d.ts

@@ -0,0 +1,99 @@
+import type { Address } from "../protocol/index.js";
+import type { Deployment } from "../chain/index.js";
+import { Hono } from "hono";
+import type { BatchingOptions } from "./batch-routes.js";
+import { BudgetedReader } from "./chain-budget.js";
+import type { ContextRecordView, RegistryReader } from "./chain-views.js";
+import { DenyOverlay } from "./deny-overlay.js";
+import type { StoredObject } from "./store.js";
+import type { ContextStores, StoreLimits } from "./stores.js";
+export declare const CANCELLATION_MAX_LIFETIME_SECONDS = 300n;
+/**
+ * How long one read-scope token — and the server-side memo it opens — may live (in-12 N-10): a
+ * handoff's 7.5 s deadline is the operation it exists for, so 8 s covers it with no room for a
+ * stale answer to outlive the operation. Fixed from first sight, never extended: a renewed token
+ * points at the same bucket, whose expiry was set when the bucket was born.
+ */
+export declare const READ_SCOPE_TTL_MS = 8000;
+/** Manifest GET responses are allowed this stale before the envelope is re-verified against Monad. */
+export declare const MANIFEST_VERIFY_CACHE_SECONDS = 60n;
+/**
+ * How far ahead of the wall clock a staged manifest's issuedAt may run. The field is written on chain
+ * time (provisionAgent stamps the latest block timestamp) and the two clocks legitimately skew — local
+ * rigs move chain time forward on purpose — so the wall clock must not hard-gate staging. The bound
+ * still rejects absurd values cheaply; the authoritative check is verifySignedManifest's, against chain
+ * time, once the agent registers — and an unverified envelope is swept at 24 h regardless.
+ */
+export declare const MANIFEST_STAGING_FUTURE_SECONDS = 86400n;
+/**
+ * The pending-bytes quota re-checks unmarked uploads in batches of 8, at most this many chain reads
+ * per PUT — and never more than the request's remaining budget after authorization
+ * (MAX_CHAIN_READS_PER_REQUEST bounds every route's total Monad reads).
+ */
+export declare const PENDING_CHECK_BATCH = 8;
+export declare const PENDING_CHECK_MAX_READS = 16;
+/**
+ * An unmarked upload only counts against the pending-bytes quota for this long. Stale orphans —
+ * uploads whose anchor transaction never landed — would otherwise sit in the quota sum forever and
+ * block every new PUT. Age is safe HERE because the quota only bounds storage cost; it is never
+ * safe in the read path, where an unmarked row must be checked against Monad however old it is —
+ * the anchored_at mark is only written on a verified read, so an old row can still hold a real
+ * record.
+ */
+export declare const PENDING_QUOTA_WINDOW_SECONDS = 86400;
+/**
+ * Per-IP request limiting, injected by the deployment. The hosted Worker's [[ratelimits]] bindings adapt
+ * to it; a self-hosted Node server may pass its own (or none — the README says a reverse proxy is needed
+ * then). `signed` tells the limiter which bucket the request counts against.
+ */
+export interface RequestLimiter {
+    check(input: {
+        ip: string;
+        signed: boolean;
+    }): Promise<boolean>;
+}
+export interface ContextApiOptions {
+    reader: RegistryReader;
+    deployment: Deployment;
+    /** The file-backed stores' directory; used only when `stores` is not given. */
+    dataDir?: string;
+    /** Injected persistence — the hosted worker passes its D1 stores here. */
+    stores?: ContextStores;
+    /** Upload-abuse limits; any field overrides the shared defaults in DEFAULT_STORE_LIMITS. */
+    limits?: Partial<StoreLimits>;
+    /** Per-IP request-rate limiting; default none (a self-hoster limits at their reverse proxy). */
+    limiter?: RequestLimiter;
+    /** Wall-clock seconds for request freshness. Chain time decides capability expiry. */
+    clock?: () => bigint;
+    /**
+     * The batched-save lane (BatchAnchor). Absent: no /batch/* surface exists and every pre-batch
+     * behaviour is unchanged. Present: the routes mount, gated inside by `batching.enabled`.
+     */
+    batching?: BatchingOptions;
+    /**
+     * The name of THIS store's RPC-endpoint setting, used in CHAIN_MISCONFIGURED/RPC_AUTH_REJECTED
+     * hints (in-14 F-4): "RPC_URL" on the hosted worker, "network.json rpcUrl" on a midad laptop
+     * store. Default is a setting-neutral "RPC endpoint".
+     */
+    rpcHint?: string;
+}
+type Env = {
+    Variables: {
+        signer: Address;
+        body: Uint8Array;
+        chain: BudgetedReader;
+    };
+};
+/** §12.3: an object is served only once Monad holds matching commitments for it. */
+export declare function isAnchored(stored: StoredObject, record: ContextRecordView | null): boolean;
+/**
+ * Minimal Context API (§12). A thin storage and authorization service, never a decryptor: it holds ciphertext,
+ * immutable manifests and reader wraps, and every agent operation passes the §12.1 ordered checks against Monad.
+ */
+export declare function createContextApi(options: ContextApiOptions): {
+    app: Hono<Env, import("hono/types").BlankSchema, "/">;
+    overlay: DenyOverlay;
+    store: import("./stores.js").ObjectStore;
+    limits: StoreLimits;
+};
+export {};

package/dist/types/api/auth-pure.d.ts

@@ -0,0 +1,51 @@
+import type { Address } from "../protocol/index.js";
+import type { NonceStore } from "./stores.js";
+/**
+ * The request-authentication pieces that touch no Node API — everything in `auth.ts` minus the
+ * file-backed ReplayGuard. They live in their own module so the owner-page bundle can reach them
+ * through `client.js` without pulling `node:fs` into a browser build: `client.js` imports from
+ * here, `auth.js` keeps ReplayGuard and re-exports this module so every existing importer of
+ * `auth.js` sees the same names it always did.
+ */
+export declare const AUTH_HEADERS: {
+    readonly signer: "x-mida-signer";
+    readonly timestamp: "x-mida-timestamp";
+    readonly nonce: "x-mida-nonce";
+    readonly signature: "x-mida-signature";
+};
+/**
+ * in-9 R-5, hardened in in-12 N-10: an optional token naming the ONE logical read operation a
+ * request belongs to (a handoff, a whats-new refresh). The server mints it — a random id, an
+ * expiry and an HMAC over the requester's own signer — and hands it out on every authenticated
+ * response, so the client only ever replays what it was issued. Requests carrying the same token
+ * share the answers their identical NON-AUTHORIZATION chain reads already paid for; a request
+ * without it, or with a forged or expired one, is simply unscoped — the token names a cache
+ * bucket, never an authorization, and authorization answers are never memoized across requests.
+ */
+export declare const READ_SCOPE_HEADER = "x-mida-read-scope";
+/** The token shape the server honors: `0x` + 64-hex random id, base-36 expiry ms, 64-hex HMAC. */
+export declare const READ_SCOPE_TOKEN_PATTERN: RegExp;
+export declare const REQUEST_WINDOW_SECONDS = 60n;
+/** Builds the §12.1 canonical target from a URL: path plus query sorted by key. Repeated keys are rejected. */
+export declare function targetOf(url: URL): string;
+/**
+ * The presence and format checks on the four authentication headers — everything that can be decided without
+ * touching state. Runs before body parsing and long before signature verification: a request whose headers
+ * are missing or malformed never costs a nonce record, a store read or a chain read.
+ */
+export declare function assertAuthHeaderShape(headers: Headers): void;
+/**
+ * §12.1 authentication: an EIP-712 MidaHttpRequestV1 signature over method, canonical target, raw body bytes,
+ * timestamp and nonce, under the "Mida Context API" domain for this chain and registry. Returns the proven signer.
+ * Authorization happens afterwards and separately.
+ */
+export declare function authenticateRequest(input: {
+    method: string;
+    url: URL;
+    headers: Headers;
+    body: Uint8Array;
+    chainId: bigint;
+    capabilityRegistry: Address;
+    now: bigint;
+    replay: NonceStore;
+}): Promise<Address>;

package/dist/types/api/auth.d.ts

@@ -0,0 +1,17 @@
+import type { Address, Hex } from "../protocol/index.js";
+import type { NonceStore } from "./stores.js";
+export { AUTH_HEADERS, READ_SCOPE_HEADER, READ_SCOPE_TOKEN_PATTERN, REQUEST_WINDOW_SECONDS, targetOf, assertAuthHeaderShape, authenticateRequest } from "./auth-pure.js";
+/**
+ * The file-backed NonceStore: a durable (signer, nonce) record for the §12.1 validity window. Each accepted pair is
+ * written to disk, atomically and synchronously, before authentication returns, so neither a restart nor a crash can
+ * forget a nonce that was accepted. Expired entries are deleted by `sweep`, which the scheduled job calls — never the
+ * request path. An unreadable store fails closed rather than starting empty.
+ */
+export declare class ReplayGuard implements NonceStore {
+    #private;
+    constructor(file: string);
+    /** Atomically checks and records a nonce; an entry already present means this exact request was seen before. */
+    consume(signer: Address, nonce: Hex, signedAt: bigint, now: bigint): Promise<void>;
+    /** Removes nonces whose signed timestamp is more than 60 seconds old; returns how many were deleted. */
+    sweep(now: bigint): Promise<number>;
+}

package/dist/types/api/authorize.d.ts

@@ -0,0 +1,24 @@
+import type { Address, AgentRecord, Hex } from "../protocol/index.js";
+import type { CapabilityView, RegistryReader } from "./chain-views.js";
+import type { DenyOverlay } from "./deny-overlay.js";
+export interface AgentAuthorization {
+    agentId: Hex;
+    agent: AgentRecord;
+    capability: CapabilityView;
+    now: bigint;
+}
+/**
+ * §12.1 normative, fail-closed validation order for every agent operation. Step 1 (authentication) has already
+ * produced `signer`. Each later step stops at the first failure with its §12.6 code. A final exact `hasAuthority`
+ * read keeps the API chain-bounded: it can deny sooner than Monad, never allow what Monad does not.
+ */
+export declare function authorizeAgent(input: {
+    reader: RegistryReader;
+    overlay: DenyOverlay;
+    signer: Address;
+    owner: Address;
+    capabilityId: Hex | undefined;
+    namespaceId: Hex;
+    permission: number;
+    agentKeyVersion?: number;
+}): Promise<AgentAuthorization>;

package/dist/types/api/batch-deny.d.ts

@@ -0,0 +1,22 @@
+import type { BatchSaveRow } from "./batch-store.js";
+import type { RegistryReader } from "./chain-views.js";
+import type { DenyOverlay } from "./deny-overlay.js";
+/** One row's answer at send time: submit it, keep it HELD, or mark it dead. */
+export type BatchGateVerdict = "send" | "hold" | "reject";
+export interface BatchRowGate {
+    /**
+     * One row's verdict. The batcher memoizes calls within a pass keyed on the fields a verdict
+     * may read — owner, signer, namespaceId, save.message.parentId, save.message.rootAuthor — so
+     * an implementation must not answer from anything else (in-11 R-9).
+     */
+    check(row: BatchSaveRow): Promise<BatchGateVerdict>;
+}
+/**
+ * The store's own deny overlay plus live Monad authority, sharing the DenyOverlay instance the
+ * HTTP routes use so a deny staged or cancelled through the API is exactly what the next tick
+ * sees. Injected per-row because the knowledge lives beside the queue, not inside the signer.
+ */
+export declare function createBatchDenyGate(input: {
+    reader: RegistryReader;
+    overlay: DenyOverlay;
+}): BatchRowGate;

package/dist/types/api/batch-routes.d.ts

@@ -0,0 +1,69 @@
+import type { Hono, MiddlewareHandler } from "hono";
+import type { LocalAccount } from "viem";
+import type { Address } from "../protocol/index.js";
+import type { Deployment } from "../chain/index.js";
+import type { BudgetedReader } from "./chain-budget.js";
+import type { DenyOverlay } from "./deny-overlay.js";
+import type { StoreLimits } from "./stores.js";
+import type { BatchStore } from "./batch-store.js";
+/** What app.ts mounts under when batching is configured; absent means no batch surface at all. */
+export interface BatchingOptions {
+    /** Kill switch — routes stay mounted but POSTs answer 503 BATCHING_DISABLED. */
+    enabled: boolean;
+    /**
+     * The BatchAnchor contract this lane anchors through. Absent only on a boot-degraded lane
+     * (`configInvalid` set) whose anchor never parsed — /batch/status then omits the field rather
+     * than echo a value a client could wrongly match on.
+     */
+    batchAnchor?: Address;
+    store: BatchStore;
+    /**
+     * Signs admission receipts; a store key, unrelated to any chain identity. Only the enabled lane
+     * ever signs — with `enabled: false` the field may be absent entirely (the worker keeps the
+     * secret optional then so a missing one cannot take the whole store down).
+     */
+    receiptAccount?: LocalAccount;
+    /**
+     * Proves batchAnchor is the contract this deployment expects — run lazily on the first batch
+     * request and cached by the implementer. A throw refuses the batch surface with its message.
+     */
+    verifyAnchor?: () => Promise<void>;
+    /**
+     * Trial gate: when present and non-empty, POST /batch/saves admits only saves whose signed
+     * owner is on this list (compared case-insensitively — entries are matched against the
+     * wire's lowercase address). Absent or empty leaves admission exactly as it was.
+     */
+    ownerAllowlist?: readonly Address[];
+    /**
+     * in-20 T-1: set when the batching configuration failed to build — a bad BATCHER_PRIVATE_KEY,
+     * a missing coordinator binding, a malformed allowlist. The store itself keeps serving; the
+     * lane reports `enabled: false, reason: "config-invalid"` and every batch write answers 503
+     * BATCH_UNAVAILABLE carrying this message, which names the variable and its rule — never its
+     * value. Reads keep answering: queue rows already stored still list.
+     */
+    configInvalid?: string;
+    /** Wake-up for the batcher, called exactly once per accepted save. */
+    notify: () => void;
+    /** Runs one submission round; invoked by POST /batch/flush after its checks pass. */
+    flush: () => Promise<void>;
+    /** Wall clock in ms — injectable so tests control receivedAt and the 10 s flush window. */
+    now?: () => number;
+}
+/** The request variables the app's middleware sets — kept structurally identical to app.ts's Env. */
+export interface BatchRouteEnv {
+    Variables: {
+        signer: Address;
+        body: Uint8Array;
+        chain: BudgetedReader;
+    };
+}
+export interface BatchRouteDeps {
+    batching: BatchingOptions;
+    deployment: Deployment;
+    limits: StoreLimits;
+    overlay: DenyOverlay;
+    authenticated: (maxBodyBytes: number) => MiddlewareHandler<BatchRouteEnv>;
+    /** The app's strict JSON body parser — INVALID_WIRE on any malformed input. */
+    json: <T>(body: Uint8Array) => T;
+}
+export declare function mountBatchRoutes(app: Hono<BatchRouteEnv>, deps: BatchRouteDeps): void;

package/dist/types/api/batch-store.d.ts

@@ -0,0 +1,96 @@
+import type { Address, Hex } from "../protocol/index.js";
+import type { BatchedReadItem, BatchedSaveWire } from "./client.js";
+/**
+ * QUEUED → SUBMITTED → ANCHORED | REJECTED, plus HELD — the in-3 state for a save whose author is
+ * on the store's active deny list. A held row is off the send path (`takeQueued` never returns it)
+ * but not dead: every batcher tick re-checks it — deny still active → stays HELD; the revoke
+ * landed → REJECTED; the deny cleared and the grant still valid → back to QUEUED and sent.
+ */
+export type BatchSaveState = "QUEUED" | "SUBMITTED" | "ANCHORED" | "REJECTED" | "HELD";
+export interface BatchSaveRow {
+    contextId: Hex;
+    owner: Address;
+    namespaceId: Hex;
+    /** Request signer that submitted the save — may GET the row without a READ grant. */
+    signer: Address;
+    /** The full signed save (message, signature, manifest, ciphertext hex). */
+    save: BatchedSaveWire;
+    state: BatchSaveState;
+    /** Rejection reason name for REJECTED rows (BATCH_REJECT keys from the contract). */
+    reason: string | null;
+    batchId: Hex | null;
+    position: number | null;
+    lineageId: Hex | null;
+    version: number | null;
+    proof: Hex[] | null;
+    /** ms since epoch when the save was accepted into the queue. */
+    receivedAt: number;
+    /** ms since epoch when the anchor confirmed, null until then. */
+    anchoredAt: number | null;
+}
+export interface BatchStore {
+    /** Returns "exists" when a row with this contextId is already stored — any state. */
+    insert(row: BatchSaveRow): Promise<"inserted" | "exists">;
+    get(contextId: Hex): Promise<BatchSaveRow | null>;
+    /** QUEUED + SUBMITTED + ANCHORED + HELD for one owner/namespace, oldest first. REJECTED never lists. */
+    listForReader(owner: Address, namespaceId: Hex): Promise<BatchSaveRow[]>;
+    /** Atomically moves up to `limit` QUEUED rows to SUBMITTED under `batchId`, oldest first. */
+    takeQueued(limit: number, batchId: Hex): Promise<BatchSaveRow[]>;
+    markAnchored(contextId: Hex, fields: {
+        batchId: Hex;
+        position: number;
+        lineageId: Hex;
+        version: number;
+        proof: Hex[];
+        anchoredAt: number;
+    }): Promise<void>;
+    markRejected(contextId: Hex, reason: string): Promise<void>;
+    /** SUBMITTED rows of `batchId` go back to QUEUED (a failed submission retried whole). */
+    requeue(batchId: Hex): Promise<number>;
+    /**
+     * One SUBMITTED row goes back to QUEUED, its batch tag cleared — a row the take could not
+     * check or could not hold retries on a later take instead of dying with its batch (in-11 R-2/R-9).
+     */
+    requeueRow(contextId: Hex): Promise<void>;
+    /** Every HELD row, oldest first — the batcher's per-tick deny re-check set. */
+    listHeld(): Promise<BatchSaveRow[]>;
+    /** A QUEUED or SUBMITTED row goes HELD; the batch tag clears so a requeue-by-batch never revives it. */
+    hold(contextId: Hex): Promise<void>;
+    /** A HELD row returns to QUEUED — the deny cleared and Monad still authorizes the save. */
+    releaseHeld(contextId: Hex): Promise<void>;
+    /** Monotonic receipt sequence — counts every accepted save, never reused. */
+    nextSequence(): Promise<bigint>;
+    countQueued(): Promise<number>;
+    /** ms since epoch of the signer's last accepted flush, or null. */
+    lastFlush(signer: Address): Promise<number | null>;
+    setLastFlush(signer: Address, atMs: number): Promise<void>;
+}
+/** The wire-facing read shape of a row — anchor fields only on ANCHORED rows. */
+export declare function batchReadItem(row: BatchSaveRow): BatchedReadItem;
+export declare class FsBatchStore implements BatchStore {
+    #private;
+    /** Rows live at `dataDir/batch/<contextId>.json`; sequence and flush marks in `dataDir/batch/meta.json`. */
+    constructor(dataDir: string);
+    insert(row: BatchSaveRow): Promise<"inserted" | "exists">;
+    get(contextId: Hex): Promise<BatchSaveRow | null>;
+    listForReader(owner: Address, namespaceId: Hex): Promise<BatchSaveRow[]>;
+    takeQueued(limit: number, batchId: Hex): Promise<BatchSaveRow[]>;
+    markAnchored(contextId: Hex, fields: {
+        batchId: Hex;
+        position: number;
+        lineageId: Hex;
+        version: number;
+        proof: Hex[];
+        anchoredAt: number;
+    }): Promise<void>;
+    markRejected(contextId: Hex, reason: string): Promise<void>;
+    requeue(batchId: Hex): Promise<number>;
+    requeueRow(contextId: Hex): Promise<void>;
+    listHeld(): Promise<BatchSaveRow[]>;
+    hold(contextId: Hex): Promise<void>;
+    releaseHeld(contextId: Hex): Promise<void>;
+    nextSequence(): Promise<bigint>;
+    countQueued(): Promise<number>;
+    lastFlush(signer: Address): Promise<number | null>;
+    setLastFlush(signer: Address, atMs: number): Promise<void>;
+}

package/dist/types/api/batcher.d.ts

@@ -0,0 +1,220 @@
+import type { LocalAccount } from "viem";
+import type { Address, Hex } from "../protocol/index.js";
+import type { Deployment } from "../chain/index.js";
+import type { BatchedSaveWire } from "./client.js";
+import type { BatchRowGate } from "./batch-deny.js";
+import type { BatchStore } from "./batch-store.js";
+/** The batcher's view of time: whoever hosts it supplies the real clock source (setTimeout, a DO alarm). */
+export interface BatcherTimer {
+    set(atMs: number): Promise<void> | void;
+    clear(): Promise<void> | void;
+    pending(): Promise<boolean> | boolean;
+}
+/** One SaveAnchored log the chain recorded for a batch — `position` is its slot in the accepted array. */
+export interface AnchoredLog {
+    contextId: Hex;
+    agentId: Hex;
+    position: number;
+    lineageId: Hex;
+    version: number;
+    leafHash: Hex;
+}
+/** One SaveRejected log — `index` is the save's position in the submitted array, not the leaf array. */
+export interface RejectedLog {
+    index: number;
+    reason: number;
+}
+/** Everything the batcher needs from Monad, and nothing more — fakes implement this in tests. */
+export interface BatcherChain {
+    /**
+     * Sends submitBatch; { exists: true } means the contract already holds this batchId
+     * (BatchExists). A real send reports the receipt's gasUsed — the measurement the batcher
+     * re-sizes the next take from. { exists: true } carries no receipt, so it carries no number.
+     */
+    submit(batchId: Hex, saves: BatchedSaveWire[]): Promise<{
+        transactionHash: Hex;
+        gasUsed: bigint;
+    } | {
+        exists: true;
+    }>;
+    anchoredLogs(batchId: Hex): Promise<AnchoredLog[]>;
+    rejectedLogs(batchId: Hex): Promise<RejectedLog[]>;
+    /** The BatchAnchored event for this batchId — who submitted it and how it split; null if none. */
+    batchAnchored(batchId: Hex): Promise<{
+        submitter: Address;
+        acceptedCount: number;
+        rejectedCount: number;
+    } | null>;
+    batchOf(batchId: Hex): Promise<{
+        root: Hex;
+        blockNumber: bigint;
+        acceptedCount: number;
+    }>;
+    /**
+     * The batchIds that anchored these contextIds, in one bounded historical scan for the whole
+     * set — used for ALREADY_ANCHORED/STALE_PARENT heals. `oldestReceivedAtMs` is the oldest
+     * receivedAt among the rows being healed: a save cannot anchor before it reached the queue, so
+     * the scan only needs the window that age implies. Map keys and values are lowercase; a
+     * contextId never anchored is simply absent.
+     */
+    findAnchorings(contextIds: Hex[], oldestReceivedAtMs: number): Promise<Map<string, Hex>>;
+}
+/**
+ * Attempt bookkeeping for an in-flight batch — the clock the unproven-retry cadence and the
+ * batch.unproven-stale alert run on. Persisted beside the batch's ordered contextIds so a restart
+ * does not reset the hour the operator's alert counts.
+ */
+export interface BatchAttempt {
+    /** ms since epoch when the batch's first submit went out. */
+    firstAt: number;
+    /** ms since epoch of the most recent submit or re-resolve attempt. */
+    lastAt: number;
+    /** How many submit/resolve attempts the batch has seen. */
+    count: number;
+}
+/**
+ * The crash-recovery journal: which batchIds are in flight and, for each, the ordered contextIds of
+ * the submitted array (the only map from SaveRejected.index back to a row). `record` is called with
+ * an empty list BEFORE the rows are even taken, then again with the real list BEFORE submit — a
+ * process that dies in either gap still leaves a discoverable batchId for `recover()` to requeue.
+ */
+export interface BatchJournal {
+    /** Every recorded batchId not yet cleared. */
+    list(): Promise<Hex[]>;
+    record(batchId: Hex, contextIds: Hex[]): Promise<void>;
+    contextIds(batchId: Hex): Promise<Hex[] | null>;
+    /** The attempt record for a journaled batch — null for one written before tracking existed. */
+    attempt(batchId: Hex): Promise<BatchAttempt | null>;
+    /** Stamps a submit/re-resolve attempt: creates the record, else moves lastAt and bumps count. */
+    noteAttempt(batchId: Hex, atMs: number): Promise<void>;
+    clear(batchId: Hex): Promise<void>;
+}
+/** Journal for tests and embedded use — process memory only, so it cannot recover a real restart. */
+export declare class MemoryBatchJournal implements BatchJournal {
+    readonly batches: Map<string, `0x${string}`[]>;
+    readonly attempts: Map<string, BatchAttempt>;
+    list(): Promise<Hex[]>;
+    record(batchId: Hex, contextIds: Hex[]): Promise<void>;
+    contextIds(batchId: Hex): Promise<Hex[] | null>;
+    attempt(batchId: Hex): Promise<BatchAttempt | null>;
+    noteAttempt(batchId: Hex, atMs: number): Promise<void>;
+    clear(batchId: Hex): Promise<void>;
+}
+/**
+ * Journal for the Node side: one JSON file beside the batch store's directory (never inside it —
+ * FsBatchStore reads every *.json under dataDir/batch/ as a row). Mutations serialize behind the same
+ * in-process promise chain the store uses.
+ */
+export declare class FsBatchJournal implements BatchJournal {
+    #private;
+    constructor(path: string);
+    list(): Promise<Hex[]>;
+    record(batchId: Hex, contextIds: Hex[]): Promise<void>;
+    contextIds(batchId: Hex): Promise<Hex[] | null>;
+    attempt(batchId: Hex): Promise<BatchAttempt | null>;
+    noteAttempt(batchId: Hex, atMs: number): Promise<void>;
+    clear(batchId: Hex): Promise<void>;
+}
+/**
+ * The Node timer: `set` replaces the pending wakeup (the batcher itself only ever asks for one at a
+ * time, or for the later gap-end instant); `unref` keeps a pending batch from holding the process open.
+ */
+export declare function createNodeTimer(fire: () => void): BatcherTimer;
+/** Thrown when the logs a chain adapter returns cannot be the batch the contract recorded. */
+export declare class BatchRootMismatchError extends Error {
+    readonly code: "ROOT_MISMATCH";
+    constructor(batchId: Hex, expected: Hex, rebuilt: Hex);
+}
+export interface BatcherOptions {
+    store: BatchStore;
+    chain: BatcherChain;
+    timer: BatcherTimer;
+    now: () => number;
+    /**
+     * The hard upper bound on saves per batch — never exceeded no matter what the gas math says.
+     * The take a run actually uses is usually smaller: the number of saves that fit the gas budget
+     * at the per-save cost learned so far.
+     */
+    cap: number;
+    /**
+     * The gas budget each take is sized against; default is the "batch.submit" ceiling. Takes are
+     * planned at 95% of it so estimate drift between sizing and sending does not turn a legal take
+     * into a refusal.
+     */
+    gasBudget?: bigint;
+    /**
+     * The per-save gas the first take assumes; default 66,264, the Sep 24 testnet sweep's measured
+     * 60-save figure (docs/evidence/batch-anchor-sweep-2026-09-24.json). The first real receipt
+     * replaces it.
+     */
+    initialGasPerSave?: bigint;
+    waitMs: number;
+    /**
+     * The batch submitter — one ingredient of the batchId and the identity resolve() proves a landed
+     * batch belongs to: submitBatch has no caller check, so an id is never trusted on its own.
+     */
+    submitter: Address;
+    /**
+     * The 32 random bytes inside each batchId — keccak(submitter, sequence, salt). The salt is what
+     * makes the next id unpredictable: a derivable id can be pre-claimed by a foreign submitBatch,
+     * which would hand that batcher's rows a stranger's outcomes. The journal records the id before
+     * the submit goes out, so recover() never needs to recompute it. Injectable for tests that must
+     * predict (or replay) an id; default is crypto.getRandomValues — present in Workers and Node.
+     */
+    salt?: () => Hex;
+    log?: (record: Record<string, unknown>) => void;
+    /** Minimum milliseconds between two real submissions; default 1000. */
+    minGapMs?: number;
+    /**
+     * Persistent record of in-flight batches — the only way `recover()` can find a batch a dead
+     * process submitted. Without one, recovery sees only this process's own submissions.
+     */
+    journal?: BatchJournal;
+    /**
+     * The per-row authority check run at send time and on every held-row re-check (in-3 I5):
+     * a row whose author sits on the store's active deny list is HELD instead of submitted — the
+     * deny overlay is the only thing that knows a revoke is pending on Monad, and the contract
+     * cannot see it. Held rows are re-checked each run: still denied → keep holding; no deny and no
+     * live authority → REJECTED with the reason the contract would have given; deny cleared and
+     * authority live → back to QUEUED and sent. A check that cannot complete parks the row back
+     * in QUEUED (in-11 R-9) — only an affirmative verdict may hold it. Absent, the batcher
+     * submits exactly as before.
+     */
+    gate?: BatchRowGate;
+}
+export declare class Batcher {
+    #private;
+    constructor(options: BatcherOptions);
+    /**
+     * One new save arrived. At the learned cap the batch goes now; below it the first save arms the
+     * wait window and every later save in the window leaves the armed timer exactly where it is.
+     */
+    notify(): Promise<void>;
+    /** Flush pokes the queue awake: drop the pending wait and run — the gap rule still applies. */
+    flush(): Promise<void>;
+    run(): Promise<{
+        batchId: Hex;
+        accepted: number;
+        rejected: number;
+    } | null>;
+    /** Re-resolve a batch against the chain — used by run() and by recover() for journaled batches. */
+    resolve(batchId: Hex): Promise<void>;
+    /**
+     * Startup recovery: every batch still recorded in the journal (plus any this process itself has
+     * in flight) is checked against the chain — landed batches resolve their rows, batches the chain
+     * never saw hand their rows back to the queue. Afterwards a non-empty queue arms the timer again.
+     */
+    recover(): Promise<void>;
+}
+/**
+ * The real chain adapter: viem clients over the deployment's RPC, submitBatch through sendContract.
+ * The send runs under the "batch.submit" ceiling (28M gas) — sized under Monad's 30M
+ * per-transaction limit rather than the 6M "revoke.agent" ceiling a batch used to borrow — and
+ * reports the receipt's gasUsed so the batcher can size the next take from the real per-save cost.
+ */
+export declare function createBatcherChain(input: {
+    rpcUrl: string;
+    deployment: Deployment;
+    account: LocalAccount;
+    now?: () => number;
+}): BatcherChain;

package/dist/types/api/browser.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The browser-safe surface of @mida/api for the owner page bundle: the hosted-store client and
+ * the chain view readers the flows need. app.ts (Hono server), auth.ts's ReplayGuard and
+ * secure-fs/stores stay out — the owner page is a client, not the server. client.js imports
+ * AUTH_HEADERS and targetOf from auth-pure.js, the node-free half of auth.ts, so nothing in this
+ * graph reaches node:fs (the bundle test scans the output for "node:").
+ * verify-assertion.js is exported as types only — its value code uses Buffer.
+ */
+export { ContextApiClient, LIST_PARTIAL_MAX_RETRIES, StoreHttpError } from "./client.js";
+export type { ContextApiClientOptions, ContextApiRoutes, ListObjectsResult } from "./client.js";
+export { RegistryReader } from "./chain-views.js";
+export type { CapabilityView, ContextRecordView } from "./chain-views.js";
+export type { AnchoredObject, ObjectUploadBody } from "./wire.js";
+export type { WebAuthnAssertionInput } from "./verify-assertion.js";