@guuey/state 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loqu, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# `@guuey/state`
+
+> Open-source KV client for MCP servers hosted on
+> [guuey.com](https://guuey.com). Scoped per `(user, mcp)`.
+> The MCP stays stateless from its own POV; the user retains
+> data ownership.
+
+## Install
+
+```sh
+npm install @guuey/state
+# or
+pnpm add @guuey/state
+```
+
+## When to reach for this
+
+You're building an MCP server hosted on guuey, and you need a small
+amount of per-user state — idempotency tokens, rate-limit counters,
+OAuth `state` nonces, user preferences a few KB in size.
+
+You should **not** reach for `@guuey/state` if you need:
+
+- More than ~1 MB of data per user (per MCP).
+- Queries / joins / indexes — KV only.
+- Cross-user shared data — scopes are strict per `(user, mcp)`.
+- Long-lived data (max TTL is 90 days; longer-lived data should
+  live in the user's own SaaS via mcp-proxy credential brokering).
+
+Those cases are explicitly out of scope. The hard caps are the
+product — per the guuey MCP Hosting Policy: most stateful MCPs only
+need a tiny bit of state (idempotency tokens, rate-limit counters,
+OAuth nonces, small preferences), and a scoped 1 MiB KV covers that
+long tail without turning guuey into a backend-as-a-service.
+
+## Quick start
+
+### Explicit context (tests, scripts)
+
+```ts
+import { createGuueyState } from "@guuey/state";
+
+const kv = createGuueyState({
+  context: { userId: "u_abc", mcpId: "mcp_xyz" },
+});
+
+await kv.set("user-prefs", { theme: "dark" }, { ttl: 60 * 60 * 24 * 7 });
+const prefs = await kv.get<{ theme: string }>("user-prefs");
+```
+
+### Implicit context (production MCP servers)
+
+You install `withGuueyContext` yourself — in production typically
+one line per request via `scopeFromAuthorization` on the Bearer JWT
+guuey sends federated servers (see "Hosted binding" below). Inside
+tool handlers you just import the barrel-exported `kv`:
+
+```ts
+import { kv } from "@guuey/state";
+
+// Inside an MCP tool handler — middleware has bound the context.
+async function handleAddTask(input: { title: string }) {
+  const seenKey = `idempotency:${hash(input.title)}`;
+  if (await kv.has(seenKey)) {
+    return { duplicate: true };
+  }
+  await kv.set(seenKey, true, { ttl: 60 });
+  // ... create the task
+  return { duplicate: false };
+}
+```
+
+If you call `kv.*` outside a context, you get a clear
+`MissingContextError` instead of silently writing to a fallback
+scope.
+
+## Hosted binding
+
+The hosted binding is a fetch-based transport that talks to guuey's KV
+API. It activates automatically when `GUUEY_KV_URL` (or
+`options.bindingUrl`) is set — nothing else about your code changes,
+because it implements the same `Kv` interface as the in-memory binding.
+
+```sh
+# .env / deploy env — bare origin, NO trailing /v1 or /v1/state.
+# The client appends `/v1/state/<op>` itself.
+GUUEY_KV_URL=https://api.dev.sandbox.guuey.com     # dev sandbox
+# GUUEY_KV_URL=https://api.staging.sandbox.guuey.com  # staging sandbox
+# GUUEY_KV_URL=https://api.us-east-1.guuey.com        # prod (region-qualified)
+```
+
+**`GUUEY_KV_URL` is injected automatically for guuey-hosted
+(`kind: 'hosted'`) and colocated (`kind: 'colocated'`, agent-pod) MCP
+servers** — no setup required, state just works. A **dev-hosted external**
+server (your own `kind: 'external'` deployment reached over a real URL,
+including federated ones) sets `GUUEY_KV_URL` itself (per-env values
+above); omitting it silently falls back to the non-durable in-memory
+binding rather than failing loud. The per-request auth token, in
+contrast, you don't provision by hand: **only federated MCP servers get
+one**, minted by the platform on every call. Set `federate: true` on an
+`external` entry in `guuey.json` (or use `kind: 'hosted'`/`kind:
+'colocated'`, or a `ggui` URL — those are federated automatically):
+
+```json
+{ "kind": "external", "url": "https://your-server.example.com", "federate": true }
+```
+
+Federation makes guuey mint a per-invoke Bearer JWT and send it as this
+server's `Authorization` header on every call. That inbound token IS
+the credential — a plain `external` entry with static `headers` gets no
+token and can't use hosted state. Derive the `ScopeContext` from it with
+`scopeFromAuthorization` and bind it per request:
+
+```ts
+import { withGuueyContext, scopeFromAuthorization, kv } from "@guuey/state";
+
+// Middleware / per-request handler — `req.headers.authorization` is the
+// Bearer JWT guuey sent this (federated) server.
+async function handler(req: { headers: { authorization?: string } }) {
+  const authHeader = req.headers.authorization;
+  if (typeof authHeader !== "string") throw new Error("missing Authorization header");
+
+  return withGuueyContext(scopeFromAuthorization(authHeader), async () => {
+    // kv.* inside here is scoped to this request's (userId, mcpId).
+    await kv.set("last-seen", Date.now(), { ttl: 60 * 60 * 24 });
+  });
+}
+```
+
+`scopeFromAuthorization` decodes the JWT client-side (unverified — the
+KV API is the verifier) into `{ userId, mcpId, token }`; the returned
+`token` is what `createGuueyState`/the ALS-bound `kv` uses to
+authenticate the hosted binding's requests, so you never touch
+`GUUEY_KV_TOKEN` yourself in this path. `mcpId` is derived from the
+JWT's `aud` claim (the server's federated resource URL) — deterministic
+and identical to the server-side derivation, so two agents pointing at
+the same external MCP share that MCP's per-user state.
+
+## API
+
+| Method                               | Purpose                                                      |
+| ------------------------------------ | ------------------------------------------------------------ |
+| `get<T>(key)`                        | Read. Returns `undefined` if absent or expired.              |
+| `set(key, value, { ttl })`           | Write. TTL required (no permanent keys).                     |
+| `delete(key)`                        | Delete (no-op if absent).                                    |
+| `has(key)`                           | Existence check.                                             |
+| `keys({ prefix?, limit?, cursor? })` | List keys, paginated (`{ keys, cursor? }`, ≤1000/page).      |
+| `increment(key, { ttl, by? })`       | Atomic counter (creates key if absent).                      |
+| `decrement(key, { ttl, by? })`       | Inverse of `increment`.                                      |
+| `mget(keys[])`                       | Bulk read.                                                   |
+| `scope()`                            | Live usage snapshot (`usedBytes`, `limitBytes`, `keyCount`). |
+
+## Limits (== the product)
+
+| Cap                | Value                | Why                                                |
+| ------------------ | -------------------- | -------------------------------------------------- |
+| Scope size         | 1 MiB                | Forces opting into a real DB beyond this.          |
+| Single value       | 64 KiB               | Large blobs → `@guuey/files` (planned).            |
+| Key length         | 1 KiB                | Keeps keys cheap to log + index.                   |
+| Key character set  | `[A-Za-z0-9_.:\-/]+` | Same set CloudWatch/Datadog use.                   |
+| TTL max            | 90 days              | Longer-lived data → user-owned SaaS via mcp-proxy. |
+| `keys()` page size | 1000                 | Diagnostics tool, not a query engine.              |
+| `mget()` batch     | 100 keys             | Bulk convenience, not a table scan.                |
+| Counters           | Safe integers only   | Rate limits + sequences; not float math.           |
+
+Sizes are **UTF-8 bytes of the key plus its JSON-encoded value** —
+keys are storage too, so a scope of long keys with tiny values
+cannot dodge the cap. The same accounting applies in every binding,
+so quota behavior is identical in tests and production.
+
+Values must be JSON-serializable: top-level `undefined`, functions,
+symbols, `BigInt`, and circular structures throw
+`InvalidArgumentError`. Standard JSON semantics otherwise apply
+(`NaN`/`Infinity` become `null`; nested `undefined` properties are
+dropped) — if that matters for your data, validate before writing.
+
+## Identity & trust model
+
+Every operation is scoped by a `ScopeContext` (`userId`, `mcpId`).
+Where those ids come from — and who is trusted to assert them —
+is the access-control story:
+
+- **In-memory binding:** the context is caller-asserted.
+  That's fine because the store is process-local — your process owns
+  all of its own data, and both ids are validated (non-empty, no
+  whitespace/control characters, ≤256 chars) to fail wiring bugs
+  loudly.
+- **Hosted binding:** the client sends the federation-minted
+  Bearer JWT (the `token` from `scopeFromAuthorization`) with every
+  request, and guuey's KV API is the verifier: it authenticates the
+  JWT and derives `userId` (the `sub` claim) and `mcpId` (hash of
+  the canonicalized `aud` resource URL) **server-side** — the
+  context the client sends is advisory-must-match, never trusted on
+  its own. An MCP server can only present tokens guuey itself minted
+  for it, so it can never reach another MCP's scopes, by
+  construction. Anonymous/guest callers get no durable scope at all —
+  their tokens are rejected outright, the same platform-layer
+  exclusion guuey applies to durable file storage. Reaching the
+  hosted binding is per-rung: guuey-hosted and colocated MCP servers
+  get `GUUEY_KV_URL` injected automatically; a dev-hosted `external`
+  server sets it itself (see "Hosted binding" above).
+- **Blast radius:** within its own app an MCP server necessarily
+  handles every one of its users' requests, so a compromised server
+  can touch its own app's scopes — never another app's. Cross-MCP
+  isolation is enforced by the storage layer, not by cooperation.
+- **Data ownership:** per-user export + delete lands in the guuey
+  console together with the hosted binding — end users can see and
+  remove what an MCP stored about them.
+
+If you outgrow any of these, you're having a **Case-B moment** (per
+the hosting policy) — build a real backend on a real cloud and treat
+that backend as your MCP's "well-defined API."
+
+## Local development
+
+Without `GUUEY_KV_URL` (or `options.bindingUrl`) the library uses the
+**in-memory binding**. It emits a one-time `console.warn` on first
+use; data is per-process and lost on restart. That's exactly right
+for tests and `guuey dev` runs.
+
+Setting `GUUEY_KV_URL` (or `options.bindingUrl`) activates the hosted
+HTTP binding — see "Hosted binding" above. It requires a token
+(`authToken`/`GUUEY_KV_TOKEN`/`context.token`) or throws
+`InvalidContextError` rather than silently handing back a non-durable
+in-memory store to a caller who explicitly asked for the durable one.
+
+## Errors
+
+Every operation that can fail throws a subclass of
+`GuueyStateError`. Use `instanceof` to discriminate:
+
+```ts
+import { kv, QuotaExceededError, InvalidKeyError } from "@guuey/state";
+
+try {
+  await kv.set("big-blob", huge, { ttl: 3600 });
+} catch (err) {
+  if (err instanceof QuotaExceededError) {
+    // Scope hit its 1 MiB ceiling. Tell the user.
+  } else if (err instanceof InvalidKeyError) {
+    // Bug in the calling code.
+  } else {
+    throw err;
+  }
+}
+```
+
+Codes: `QUOTA_EXCEEDED`, `VALUE_TOO_LARGE`, `INVALID_KEY`,
+`INVALID_TTL`, `INVALID_ARGUMENT`, `INVALID_CONTEXT`,
+`TYPE_MISMATCH`, `MISSING_CONTEXT`, `TRANSPORT`.
+
+## What this library is NOT
+
+- **Not a database.** No queries, joins, transactions across keys,
+  or secondary indexes.
+- **Not durable beyond 90 days.** Longer-lived storage is the user's
+  own SaaS via mcp-proxy.
+- **Not cross-MCP.** Two MCPs cannot share data via `@guuey/state`
+  even for the same user — by design.
+- **Not for storing the agent's chat history** — the platform's
+  managed conversation history already handles that.
+
+## Status
+
+🧪 **Developer preview (`0.x`).** The API surface, error shapes, and
+hard caps are **locked and enforced** — code written against this
+package today keeps working unchanged when the hosted binding ships.
+What exists vs. what's coming:
+
+| Piece                                       | Status                                 |
+| ------------------------------------------- | -------------------------------------- |
+| `Kv` API, typed errors, context middleware  | ✅ locked + tested                     |
+| Cap enforcement (scope/value/TTL/key rules) | ✅ enforced in every binding           |
+| In-memory binding (dev, tests)              | ✅ shipped                             |
+| Hosted binding (durable, cross-pod)         | ✅ shipped (dev gate green 2026-07-27) |
+| Console export + delete (data ownership)    | ✅ shipped with the hosted binding     |
+
+The hosted-binding client (`HttpKv`) and its server counterpart already
+ship — the 🔜 rows track **per-environment availability** (whether
+`GUUEY_KV_URL` points at a live gateway in your environment), not
+whether the code exists.
+
+Until the hosted binding is live in your environment, state is
+per-pod and non-durable — design your MCP so that losing this state
+is an inconvenience (re-auth, cache miss), never data loss.

package/dist/context.d.ts

@@ -0,0 +1,37 @@
+import type { ScopeContext } from "./types.js";
+/**
+ * Reject unusable scope ids at bind time. Scope ids are
+ * platform-issued opaque identifiers (Cognito subs, app ids) —
+ * whitespace or control characters in one is always a wiring bug,
+ * and catching it here beats a scope-ambiguity bug in storage.
+ * Shared by `withGuueyContext` and `createGuueyState` so both
+ * entry points enforce the same contract.
+ */
+export declare function validateContext(context: ScopeContext): void;
+/**
+ * Run `fn` with the given scope context bound to AsyncLocalStorage.
+ * Nested calls override the outer context for their lifetime.
+ *
+ * The MCP server frameworks (express/fastify/hono middleware,
+ * `@modelcontextprotocol/sdk` transports) call this once per
+ * incoming request after extracting the user/mcp ids from headers
+ * or the SDK's session context.
+ */
+export declare function withGuueyContext<T>(context: ScopeContext, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Current scope context, or `undefined` if none is bound. The
+ * library's barrel-exported `kv` calls this on every operation
+ * and throws `MissingContextError` when it returns `undefined`.
+ */
+export declare function getCurrentContext(): ScopeContext | undefined;
+/**
+ * Derive a ScopeContext from the Authorization header guuey sent this
+ * MCP server. Decodes WITHOUT verifying — the KV API is the verifier;
+ * this is DX so `withGuueyContext(scopeFromAuthorization(h), fn)` is
+ * one line. mcpId = "mcp_" + first 32 hex of sha256(canonical aud URL),
+ * identical to the server derivation (auth.ts — keep in sync).
+ */
+export declare function scopeFromAuthorization(header: string): ScopeContext;
+/** Canonicalize + hash a resource URL into a scope-safe mcpId. */
+export declare function mcpIdFromResourceUrl(url: string): string;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAgB3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAWZ;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,GAAG,SAAS,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAuBnE;AAED,kEAAkE;AAClE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIxD"}

package/dist/context.js

@@ -0,0 +1,114 @@
+/**
+ * AsyncLocalStorage-based scope context.
+ *
+ * Two ways to feed a `ScopeContext` to the library:
+ *
+ * 1. **Explicit per-call** — pass `{ context }` to
+ *    `createGuueyState`. Best for tests, scripts, and code that
+ *    runs outside an HTTP request lifecycle.
+ *
+ * 2. **Implicit via AsyncLocalStorage** — wrap the request
+ *    handler in `withGuueyContext` and use the barrel-exported
+ *    `kv` (or call `getCurrentContext()` directly). This is
+ *    what guuey-hosted MCP servers do: a middleware reads
+ *    `X-Guuey-User-Id` + `X-Guuey-Mcp-Id` headers per request
+ *    and calls `withGuueyContext(...)` for the handler body.
+ *
+ * Why AsyncLocalStorage and not a plain module-level variable:
+ * concurrent requests on the same Node.js process can be in
+ * different scopes simultaneously. ALS gives us per-async-chain
+ * isolation.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+import { InvalidContextError } from "./errors.js";
+const storage = new AsyncLocalStorage();
+/**
+ * Reject unusable scope ids at bind time. Scope ids are
+ * platform-issued opaque identifiers (Cognito subs, app ids) —
+ * whitespace or control characters in one is always a wiring bug,
+ * and catching it here beats a scope-ambiguity bug in storage.
+ * Shared by `withGuueyContext` and `createGuueyState` so both
+ * entry points enforce the same contract.
+ */
+export function validateContext(context) {
+    for (const field of ["userId", "mcpId"]) {
+        const value = context[field];
+        if (typeof value !== "string" || value.length === 0) {
+            throw new InvalidContextError(field, "must be a non-empty string");
+        }
+        if (/[\s\p{Cc}]/u.test(value)) {
+            throw new InvalidContextError(field, "must not contain whitespace or control characters");
+        }
+        if (value.length > 256) {
+            throw new InvalidContextError(field, "must be <= 256 characters");
+        }
+    }
+}
+/**
+ * Run `fn` with the given scope context bound to AsyncLocalStorage.
+ * Nested calls override the outer context for their lifetime.
+ *
+ * The MCP server frameworks (express/fastify/hono middleware,
+ * `@modelcontextprotocol/sdk` transports) call this once per
+ * incoming request after extracting the user/mcp ids from headers
+ * or the SDK's session context.
+ */
+export function withGuueyContext(context, fn) {
+    // Validation failures surface as a rejected promise (matching the
+    // return type), never a synchronous throw. `storage.run` itself must
+    // stay synchronous — AsyncLocalStorage binds the context only for
+    // the synchronous extent of `run`, and `fn` starts inside it.
+    try {
+        validateContext(context);
+    }
+    catch (err) {
+        return Promise.reject(err);
+    }
+    return Promise.resolve(storage.run(context, fn));
+}
+/**
+ * Current scope context, or `undefined` if none is bound. The
+ * library's barrel-exported `kv` calls this on every operation
+ * and throws `MissingContextError` when it returns `undefined`.
+ */
+export function getCurrentContext() {
+    return storage.getStore();
+}
+/**
+ * Derive a ScopeContext from the Authorization header guuey sent this
+ * MCP server. Decodes WITHOUT verifying — the KV API is the verifier;
+ * this is DX so `withGuueyContext(scopeFromAuthorization(h), fn)` is
+ * one line. mcpId = "mcp_" + first 32 hex of sha256(canonical aud URL),
+ * identical to the server derivation (auth.ts — keep in sync).
+ */
+export function scopeFromAuthorization(header) {
+    const m = /^Bearer\s+(.+)$/i.exec(header.trim());
+    if (!m)
+        throw new InvalidContextError("token", "not a Bearer authorization header");
+    const token = m[1] ?? "";
+    const parts = token.split(".");
+    if (parts.length !== 3 || parts[1] === undefined) {
+        throw new InvalidContextError("token", "malformed JWT");
+    }
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    }
+    catch {
+        throw new InvalidContextError("token", "JWT payload is not valid JSON");
+    }
+    const aud = Array.isArray(payload.aud) ? payload.aud[0] : payload.aud;
+    if (typeof payload.sub !== "string" || payload.sub.length === 0)
+        throw new InvalidContextError("userId", "JWT has no sub claim");
+    if (typeof aud !== "string" || aud.length === 0)
+        throw new InvalidContextError("mcpId", "JWT has no aud claim");
+    return { userId: payload.sub, mcpId: mcpIdFromResourceUrl(aud), token };
+}
+/** Canonicalize + hash a resource URL into a scope-safe mcpId. */
+export function mcpIdFromResourceUrl(url) {
+    const u = new URL(url);
+    const canonical = `${u.protocol.toLowerCase()}//${u.host.toLowerCase()}${u.pathname.replace(/\/+$/, "")}`;
+    return `mcp_${createHash("sha256").update(canonical).digest("hex").slice(0, 32)}`;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Typed error hierarchy for `@guuey/state`. Every operation that
+ * can fail throws a subclass of `GuueyStateError`, so call sites
+ * can `instanceof`-discriminate without parsing message strings.
+ */
+export declare class GuueyStateError extends Error {
+    /** Stable, machine-readable error code. */
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The scope is at or above its byte limit. Thrown by `set` and
+ * `increment` when the write would push usage past the cap.
+ * Includes the live `usedBytes` + `limitBytes` so the caller can
+ * surface a meaningful error to the user.
+ */
+export declare class QuotaExceededError extends GuueyStateError {
+    readonly usedBytes: number;
+    readonly limitBytes: number;
+    constructor(usedBytes: number, limitBytes: number);
+}
+/**
+ * A single value exceeds the per-value cap. Today: 64 KiB.
+ * Large blobs belong in `@guuey/files` (planned), not in KV.
+ */
+export declare class ValueTooLargeError extends GuueyStateError {
+    readonly valueBytes: number;
+    readonly limitBytes: number;
+    constructor(valueBytes: number, limitBytes: number);
+}
+/**
+ * Key string is too long or contains a forbidden character. Today:
+ * 1 KiB max length; ASCII letters, digits, and `_.:-/` only
+ * (the standard "URL-safe-ish" set). Keeps keys cheap to log + index.
+ */
+export declare class InvalidKeyError extends GuueyStateError {
+    readonly key: string;
+    constructor(key: string, reason: string);
+}
+/**
+ * TTL is missing, zero, negative, or above the 90-day cap.
+ */
+export declare class InvalidTtlError extends GuueyStateError {
+    readonly ttl: unknown;
+    constructor(ttl: unknown, reason: string);
+}
+/**
+ * The library was called without a `ScopeContext` — either no
+ * `createGuueyState({ context })` AND no surrounding
+ * `withGuueyContext(...)` block. Common in unit tests that import
+ * `kv` from the barrel without setting up context.
+ */
+export declare class MissingContextError extends GuueyStateError {
+    constructor();
+}
+/**
+ * `increment`/`decrement` was called on a key whose stored value is
+ * not a number. Counter ops require number-typed keys; mixing a
+ * counter and a JSON value under one key is a calling-code bug.
+ */
+export declare class TypeMismatchError extends GuueyStateError {
+    readonly key: string;
+    readonly actualType: string;
+    constructor(key: string, actualType: string);
+}
+/**
+ * A per-call argument is unusable — a `keys()` limit outside
+ * 1..1000, an `mget` batch over 100 keys, a non-integer counter
+ * step, or a value that isn't JSON-serializable (top-level
+ * `undefined`/function/symbol, `BigInt`, circular structure).
+ * Distinct from `InvalidKeyError`/`InvalidTtlError`, which cover the
+ * key and TTL contracts specifically.
+ */
+export declare class InvalidArgumentError extends GuueyStateError {
+    constructor(reason: string);
+}
+/**
+ * A `ScopeContext` field is unusable — an id that is empty or contains
+ * whitespace/control characters, or a missing `token` when the hosted
+ * binding was explicitly requested. Scope ids are platform-issued
+ * opaque identifiers (Cognito subs, app ids); anything with
+ * whitespace in it is a wiring bug at the call site, and the
+ * storage layer refuses it rather than risking scope ambiguity.
+ */
+export declare class InvalidContextError extends GuueyStateError {
+    readonly field: "userId" | "mcpId" | "token";
+    constructor(field: "userId" | "mcpId" | "token", reason: string);
+}
+/**
+ * The KV binding's transport call failed (HTTP 5xx, network blip,
+ * timeout). Includes the underlying cause for diagnostics. The
+ * caller may safely retry idempotent reads.
+ */
+export declare class TransportError extends GuueyStateError {
+    constructor(message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKzE;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,eAAe;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAWlD;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,eAAe;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAUnD;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,eAAe;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAET,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAOxC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,eAAe;IAClD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;gBAEV,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM;CAKzC;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;;CAUvD;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,eAAe;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAU5C;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,SAAQ,eAAe;gBAC3C,MAAM,EAAE,MAAM;CAI3B;AAED;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;IACtD,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;gBAEjC,KAAK,EAAE,QAAQ,GAAG,OAAO,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM;CAKhE;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,eAAe;gBACrC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C"}