@covia/covia-sdk 1.6.0-next.0 → 1.7.0

package/README.md

@@ -118,8 +118,26 @@ venue.metadata;   // { name, description }
 | `venue.didDocument()` | Get the venue's DID document |
 | `venue.mcpDiscovery()` | Get MCP (Model Context Protocol) discovery info |
 | `venue.agentCard()` | Get A2A (Agent-to-Agent) agent card |
+| `venue.setPrivate(enabled)` | Toggle private-jobs mode for this connection (see below) |
 | `venue.close()` | Release resources and clear caches |
 
+#### Private jobs
+
+`venue.setPrivate(true)` puts the connection in **private-jobs mode**: every
+subsequent `operations.run()` executes as a memory-only job — never persisted
+to the venue's job index, gone on venue restart. The venue must have
+`enablePrivateJobs` set. Because a completed private job is immediately
+forgotten by the venue, results are collected through the server-side invoke
+`wait` window rather than polling — so private mode works with `run()`, and
+poll-style `operations.invoke()` throws.
+
+```typescript
+venue.setPrivate(true);
+const result = await venue.operations.run("v/ops/schema/infer", {
+  value: { name: "Ada", age: 36 },
+});
+```
+
 ---
 
 ### Operations — `venue.operations`
@@ -160,6 +178,22 @@ const job = await venue.operations.invoke("sensitive:op", input, {
 
 ---
 
+### Adapters — `venue.adapters`
+
+List the adapters registered on a venue — the true registry, including adapters
+with zero catalogued operations. Backed by the venue's canonical
+`v/info/adapters/<name>` lattice data, read job-free via the values API.
+
+```typescript
+// All registered adapters
+const adapters = await venue.adapters.list();
+adapters.forEach((a) => console.log(`${a.name}: ${a.operations.length} ops`));
+
+// One adapter's summary (null if not registered)
+const covia = await venue.adapters.get("covia");
+console.log(covia?.description, covia?.operations);
+```
+
 ### Assets — `venue.assets`
 
 Manage data assets and operations registered on the venue.
@@ -430,34 +464,42 @@ await venue.agents.chat("my-agent", "hi");
 
 Read and write shared state in the venue's workspace.
 
+**Reads are job-free.** `read`/`list`/`slice`/`inspect`/`count`/`aggregate` go through
+`GET /api/v1/values/*` (covia #177) — synchronous, capability-checked, and **no job is
+persisted**. This matters under load: routing reads through the invoke/job path writes a
+durable job record per read, growing the venue's etch without bound. **Writes stay on the
+job path** (they should leave an audit record). A read that needs UCAN **proof tokens**
+(cross-DID) transparently falls back to the invoke path.
+
 ```typescript
-// CRUD
+// CRUD (reads are job-free; writes are jobs)
 await venue.workspace.write("w/my-app/config", { theme: "dark" });
 const data = await venue.workspace.read("w/my-app/config");
 await venue.workspace.append("w/my-app/log", "new entry");
 await venue.workspace.delete("w/my-app/config");
 
 // List and slice
-const entries = await venue.workspace.list("w/my-app/", 100, 0);
+const entries = await venue.workspace.list("w/my-app/log", 100, 0);
 const slice = await venue.workspace.slice("w/my-app/log", 0, 10);
 
-// Discovery
-const funcs = await venue.workspace.functions();
-const desc = await venue.workspace.describe("myFunction");
-const adapters = await venue.workspace.adapters();
+// Server-side tallies — count / group-by without reading every record
+const { count } = await venue.workspace.count("w/my-app/log", { depth: 1 });
+const byKind = await venue.workspace.aggregate("w/my-app/events", { depth: 2, groupBy: "kind" });
+// byKind.groups → { click: { count: 12 }, view: { count: 40 } }
 ```
 
 | Method | Returns | Description |
 |---|---|---|
-| `workspace.read(path, maxSize?)` | `WorkspaceReadResult` | Read a value |
-| `workspace.write(path, value)` | `WorkspaceWriteResult` | Write a value |
-| `workspace.delete(path)` | `WorkspaceDeleteResult` | Delete an entry |
-| `workspace.append(path, value)` | `WorkspaceAppendResult` | Append to an entry |
-| `workspace.list(path?, limit?, offset?)` | `WorkspaceListResult` | List entries |
-| `workspace.slice(path, offset?, limit?)` | `WorkspaceSliceResult` | Slice an entry |
-| `workspace.functions()` | `FunctionsResult` | List available functions |
-| `workspace.describe(name)` | `any` | Describe a function |
-| `workspace.adapters()` | `AdaptersResult` | List adapters |
+| `workspace.read(path, maxSize?)` | `WorkspaceReadResult` | Read a value (job-free) |
+| `workspace.write(path, value)` | `WorkspaceWriteResult` | Write a value (job) |
+| `workspace.delete(path)` | `WorkspaceDeleteResult` | Delete an entry (job) |
+| `workspace.append(path, value)` | `WorkspaceAppendResult` | Append to an entry (job) |
+| `workspace.list(path?, limit?, offset?)` | `WorkspaceListResult` | List keys/count of a node (job-free) |
+| `workspace.slice(path, offset?, limit?)` | `WorkspaceSliceResult` | Paginated elements/entries (job-free) |
+| `workspace.inspect(paths, budget?, compact?)` | `WorkspaceInspectResult` | JSON5 render of a value (job-free; single path) |
+| `workspace.count(path, {depth?})` | `WorkspaceCountResult` | Count entries at a depth (job-free) |
+| `workspace.aggregate(path, {depth?, groupBy?})` | `WorkspaceAggregateResult` | Count, optionally grouped by a field (job-free) |
+| `workspace.copy(from, to)` | `WorkspaceCopyResult` | Copy a value between paths (job) |
 
 ---
 
@@ -466,9 +508,8 @@ const adapters = await venue.workspace.adapters();
 Manage secrets stored on the venue.
 
 ```typescript
-// Store and retrieve
-await venue.secrets.put("API_KEY", "sk-...");
-await venue.secrets.set("API_KEY", "sk-..."); // via secret:set operation
+// Store a secret (returns SecretSetResult)
+await venue.secrets.set("API_KEY", "sk-...");
 
 // List
 const names = await venue.secrets.list(); // ["API_KEY", "DB_PASS"]
@@ -483,8 +524,7 @@ await venue.secrets.delete("API_KEY");
 | Method | Returns | Description |
 |---|---|---|
 | `secrets.list()` | `string[]` | List secret names |
-| `secrets.put(name, value)` | `void` | Store a secret via REST |
-| `secrets.set(name, value)` | `SecretSetResult` | Store via `secret:set` operation |
+| `secrets.set(name, value)` | `SecretSetResult` | Store a secret (`secret:set`) |
 | `secrets.extract(name)` | `SecretExtractResult` | Extract value (requires UCAN) |
 | `secrets.delete(name)` | `void` | Delete a secret |
 
@@ -503,7 +543,31 @@ const token = await venue.ucan.issue("did:key:z6MkBob", att, exp);
 
 | Method | Returns | Description |
 |---|---|---|
-| `ucan.issue(aud, att, exp)` | `UCANIssueResult` | Issue a UCAN token |
+| `ucan.issue(aud, att, exp)` | `UCANIssueResult` | Issue a venue-signed UCAN token |
+| `ucan.verify(token, check?)` | `UCANVerifyResult` | Diagnose a token against the venue's trust policy |
+
+`ucan.verify` explains a token's verdict — `valid`/`reason`, `chainDepth`,
+`rootIssuer`, and a per-capability `rootAuthority` (`owner` / `venue` /
+`refused`). Pass `check: { with, can, aud }` to also ask whether the token
+would authorise a specific request (`authorises`).
+
+#### Client-side minting
+
+Tokens can also be minted locally with your own Ed25519 key — no venue
+round-trip:
+
+```typescript
+import { grant, identityToken, relayDelegation, didFor } from "@covia/covia-sdk";
+
+// Self-sovereign grant over your own namespace — verifies on ANY venue
+const token = grant(privateKey, "did:key:z6MkBob", `${didFor(privateKey)}/w/shared/`, "crud/read", 3600);
+
+// Identity token — proves control of your DID to a venue (empty attenuation)
+const idToken = identityToken(privateKey, venue.venueId);
+
+// Relay delegation — authorises the venue to forward your authority cross-venue
+const relay = relayDelegation(privateKey, venue.venueId, 300, [{ with: `${didFor(privateKey)}/w/`, can: "crud/read" }]);
+```
 
 ---
 
@@ -521,6 +585,7 @@ import {
   CoviaConnectionError,// Connection failures
   CoviaTimeoutError,   // Timeout exceeded
   JobFailedError,      // Job finished with non-COMPLETE status
+  RateLimitError,      // 429 after bounded retries (carries retryAfterSeconds)
 } from "@covia/covia-sdk";
 
 try {
@@ -573,7 +638,7 @@ RunStatus.AUTH_REQUIRED;   // Waiting for authentication
 ```typescript
 import {
   Venue, Grid, Job, Agent, ChatSession, Asset, Operation, DataAsset,
-  AssetManager, OperationManager, JobManager,
+  AdapterManager, AssetManager, OperationManager, JobManager,
   AgentManager, WorkspaceManager, SecretManager, UCANManager,
   KeyPairAuth, BearerAuth,
   RunStatus, CoviaError,