oceum 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # oceum
 
-Official SDK for [Oceum](https://oceum.ai) — governed agent infrastructure. Progressive autonomy, zero-knowledge vault, governed execution, and enterprise-grade observability.
+Official SDK for [Oceum](https://oceum.ai) — governed agent infrastructure. Progressive autonomy, blind-relay vault (the agent never sees the secret), governed execution, and enterprise-grade observability.
 
 Zero dependencies. Works with Node.js 18+, Deno, and Bun.
 
@@ -148,6 +148,54 @@ try {
 }
 ```
 
+## Optimistic Concurrency (v0.5.0)
+
+Avoid silently overwriting fresher state when two writers race for the same row.
+
+### When to use
+
+- You read a vault entry, present it to the user for editing, and want to make sure no other process modified it before the user submits.
+- Your agent reads a memory entry, derives a decision, and writes back — and another agent might be doing the same thing concurrently.
+- You're updating an integration's config and another admin might be doing the same in another tab.
+
+### Pattern
+
+```javascript
+const { Oceum, OceumConflictError } = require('oceum');
+const oceum = new Oceum({ apiKey: 'oc_xxx', agentId: 'agt_xxx' });
+
+// 1. Read with hash
+const { data, hash } = await oceum.vaultReadWithHash('vtk_xxx');
+
+// 2. Modify
+const newPayload = { label: 'Updated label' };
+
+// 3. Write expecting the original hash
+try {
+  const { hash: newHash } = await oceum.vaultWriteExpecting('vtk_xxx', hash, newPayload);
+  console.log('Saved. New hash:', newHash);
+} catch (err) {
+  if (err instanceof OceumConflictError) {
+    // Another writer beat you to it. err.current is the latest server state.
+    console.warn('Conflict! Server has:', err.current);
+    // Re-read, merge, retry — or surface to the user.
+  } else {
+    throw err;
+  }
+}
+```
+
+Same pattern for memory and integrations:
+- `oceum.memoryReadWithHash(memoryId)` / `oceum.memoryWriteExpecting(memoryId, hash, payload)`
+- `oceum.integrationReadWithHash(integrationId)` / `oceum.integrationWriteExpecting(integrationId, hash, payload)`
+
+### Important notes
+
+- **Do NOT use on memory rows whose name starts with `pulse-`** — those are system-internal upserts and may cause spurious 409s.
+- The SDK does NOT auto-retry on 409 — re-attempting with the same stale hash would just 409 again. Caller must re-read first.
+- 5xx errors and network errors retry as before (exponential backoff, MAX_RETRIES=3).
+- The SDK sends `If-Match: <hash>` HTTP header — RFC 7232 standard. Server returns the new hash in the response body and as an `ETag` header.
+
 ## Webhook Verification
 
 Verify incoming webhook signatures with HMAC-SHA256:

package/index.d.ts

@@ -35,6 +35,33 @@ export class OceumError extends Error {
   constructor(message: string, statusCode: number, body: Record<string, unknown>);
 }
 
+/** Phase 36 (v0.5.0): conflict body shape returned by writeExpecting on 409. */
+export interface ConflictBody {
+  current: Record<string, unknown>;
+  currentHash: string;
+  attemptedHash: string;
+}
+
+/**
+ * Phase 36 (v0.5.0): thrown when a writeExpecting call hits a hash mismatch (409).
+ * Carries the current row + currentHash so the consumer can immediately
+ * decide whether to merge, retry, or surface to the user.
+ */
+export class OceumConflictError extends OceumError {
+  /** The current row state (server-authoritative) */
+  readonly current: Record<string, unknown>;
+  /** The version_hash currently stored */
+  readonly currentHash: string;
+  /** The hash the SDK caller sent in If-Match */
+  readonly attemptedHash: string;
+  constructor(
+    message: string,
+    current: Record<string, unknown>,
+    currentHash: string,
+    attemptedHash: string,
+  );
+}
+
 export class Oceum {
   constructor(config: OceumConfig);
 
@@ -86,7 +113,7 @@ export class Oceum {
   vaultRetrieve(token: string): Promise<VaultRetrieveResponse>;
 
   /**
-   * Zero-Knowledge Vault Proxy — make an API call with a vault-stored credential
+   * Blind-Relay Vault Proxy — make an API call with a vault-stored credential
    * without ever seeing the raw secret.
    */
   vaultProxy(token: string, request: VaultProxyRequest): Promise<VaultProxyResponse>;
@@ -97,6 +124,43 @@ export class Oceum {
   /** List vault tokens (metadata only). */
   vaultList(options?: VaultListOptions): Promise<VaultListResponse>;
 
+  // ── Phase 36: Optimistic Concurrency (v0.5.0) ───────────────────
+
+  /**
+   * Read a vault token along with its version_hash for optimistic concurrency.
+   * Use the returned hash with vaultWriteExpecting to safely update the token.
+   */
+  vaultReadWithHash(token: string): Promise<{ data: string; hash: string }>;
+
+  /**
+   * Write a vault token expecting the row to currently match `hash`.
+   * Throws OceumConflictError on hash mismatch (409). Does NOT auto-retry.
+   */
+  vaultWriteExpecting(token: string, hash: string, payload: Record<string, unknown>): Promise<{ ok: boolean; hash: string }>;
+
+  /**
+   * Read a memory entry along with its version_hash.
+   * Do NOT use on memory rows whose name starts with `pulse-` (system-internal upserts).
+   */
+  memoryReadWithHash(memoryId: string): Promise<{ data: Record<string, unknown>; hash: string }>;
+
+  /**
+   * Write a memory entry expecting the row to currently match `hash`.
+   * Throws OceumConflictError on hash mismatch (409). Does NOT auto-retry.
+   */
+  memoryWriteExpecting(memoryId: string, hash: string, payload: Record<string, unknown>): Promise<{ ok: boolean; hash: string }>;
+
+  /**
+   * Read an integration entry along with its version_hash.
+   */
+  integrationReadWithHash(integrationId: string): Promise<{ data: Record<string, unknown>; hash: string }>;
+
+  /**
+   * Write an integration entry expecting the row to currently match `hash`.
+   * Throws OceumConflictError on hash mismatch (409). Does NOT auto-retry.
+   */
+  integrationWriteExpecting(integrationId: string, hash: string, payload: Record<string, unknown>): Promise<{ ok: boolean; hash: string }>;
+
   /**
    * Verify a webhook signature using HMAC-SHA256 with timing-safe comparison.
    * @returns true if the signature is valid

package/index.js

@@ -14,6 +14,33 @@ class OceumError extends Error {
   }
 }
 
+/**
+ * Phase 36 (v0.5.0): thrown when a writeExpecting call hits a hash mismatch (409).
+ * Carries the current row + currentHash so the consumer can immediately
+ * decide whether to merge, retry, or surface to the user.
+ *
+ * Example:
+ *   try {
+ *     await oceum.memoryWriteExpecting('mem-1', oldHash, { content: 'X' });
+ *   } catch (err) {
+ *     if (err instanceof OceumConflictError) {
+ *       console.warn('Conflict! Server has:', err.current);
+ *       // Re-read, merge, retry — or surface to the user.
+ *     } else {
+ *       throw err;
+ *     }
+ *   }
+ */
+class OceumConflictError extends OceumError {
+  constructor(message, current, currentHash, attemptedHash) {
+    super(message, 409, { current, currentHash, attemptedHash });
+    this.name = 'OceumConflictError';
+    this.current = current;
+    this.currentHash = currentHash;
+    this.attemptedHash = attemptedHash;
+  }
+}
+
 class Oceum {
   #apiKey;
   #agentId;
@@ -104,6 +131,83 @@ class Oceum {
       : new OceumError(lastError?.message || 'Request failed after retries', 0, {});
   }
 
+  /**
+   * Phase 36: variant of #send that adds extra HTTP headers (e.g. If-Match).
+   * On 409 response, throws OceumConflictError instead of OceumError.
+   * Does NOT auto-retry on 409 (caller must re-read first — re-attempting
+   * with the same stale hash would just 409 again).
+   */
+  async #sendWithHeaders(event, data = {}, headers = {}) {
+    let lastError;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        const res = await fetch(`${this.#baseUrl}/api/webhook`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.#apiKey}`,
+            ...headers,
+          },
+          body: JSON.stringify({
+            event,
+            agentId: this.#agentId,
+            data,
+          }),
+        });
+
+        // 409 — never retry; throw OceumConflictError immediately.
+        if (res.status === 409) {
+          const body = await res.json().catch(() => ({}));
+          throw new OceumConflictError(
+            body.error || 'version_hash mismatch',
+            body.current,
+            body.currentHash,
+            body.attemptedHash,
+          );
+        }
+
+        // 429 — respect Retry-After header
+        if (res.status === 429 && attempt < MAX_RETRIES) {
+          const retryAfter = parseInt(res.headers.get('Retry-After'), 10);
+          const waitMs = (retryAfter > 0 ? retryAfter : 1) * 1000;
+          await this.#sleep(waitMs);
+          continue;
+        }
+
+        // 5xx — exponential backoff (matches #send behavior)
+        if (res.status >= 500 && attempt < MAX_RETRIES) {
+          await this.#sleep(BACKOFF_BASE_MS * Math.pow(2, attempt));
+          continue;
+        }
+
+        const body = await res.json().catch(() => ({}));
+
+        if (!res.ok) {
+          throw new OceumError(
+            body.error || `HTTP ${res.status}`,
+            res.status,
+            body,
+          );
+        }
+
+        return body;
+      } catch (err) {
+        lastError = err;
+        if (err instanceof OceumConflictError) throw err; // never retry conflicts
+        if (err instanceof OceumError) throw err;
+        if (attempt < MAX_RETRIES) {
+          await this.#sleep(BACKOFF_BASE_MS * Math.pow(2, attempt));
+          continue;
+        }
+      }
+    }
+
+    throw lastError instanceof OceumError
+      ? lastError
+      : new OceumError(lastError?.message || 'Request failed after retries', 0, {});
+  }
+
   async #get(url) {
     let lastError;
 
@@ -384,7 +488,7 @@ class Oceum {
   }
 
   /**
-   * Zero-Knowledge Vault Proxy — make an API call with a vault-stored credential
+   * Blind-Relay Vault Proxy — make an API call with a vault-stored credential
    * without ever seeing the raw secret. The platform decrypts and injects the
    * credential into the outgoing request, then returns only the API response.
    *
@@ -424,10 +528,91 @@ class Oceum {
     return this.#get(`${this.#baseUrl}/api/vault?${params}`);
   }
 
+  // ── Phase 36: Optimistic Concurrency (v0.5.0) ──────
+
+  /**
+   * Read a vault token along with its version_hash for optimistic concurrency.
+   * Use the returned hash with vaultWriteExpecting to safely update the token
+   * without overwriting changes from a concurrent writer.
+   * @param {string} token - Vault token (vtk_xxx)
+   * @returns {Promise<{data: string, hash: string}>}
+   */
+  async vaultReadWithHash(token) {
+    const res = await this.#send('vault_retrieve', { token });
+    return { data: res.data, hash: res.version_hash };
+  }
+
+  /**
+   * Write a vault token expecting the row to currently match `hash`.
+   * Throws OceumConflictError on hash mismatch (409). Does NOT retry on 409.
+   * @param {string} token - Vault token (vtk_xxx)
+   * @param {string} hash - The hash returned from the previous vaultReadWithHash
+   * @param {Object} payload - Update fields (label, accessPolicy, etc.)
+   * @returns {Promise<{ok: boolean, hash: string}>}
+   */
+  async vaultWriteExpecting(token, hash, payload) {
+    if (!hash) throw new Error('oceum: vaultWriteExpecting requires a hash from vaultReadWithHash');
+    const res = await this.#sendWithHeaders('vault_update', { token, ...payload }, { 'If-Match': hash });
+    return { ok: true, hash: res.version_hash };
+  }
+
+  /**
+   * Read a memory entry along with its version_hash.
+   *
+   * NOTE: do NOT use on memory rows whose name starts with `pulse-` —
+   * those are system-internal upserts (Pitfall 5). Use is unsupported and
+   * may cause spurious 409s.
+   *
+   * @param {string} memoryId
+   * @returns {Promise<{data: Object, hash: string}>}
+   */
+  async memoryReadWithHash(memoryId) {
+    const res = await this.#send('memory_read_one', { memoryId });
+    return { data: res.memory, hash: res.memory && res.memory.version_hash };
+  }
+
+  /**
+   * Write a memory entry expecting the row to currently match `hash`.
+   * Throws OceumConflictError on hash mismatch (409). Does NOT retry on 409.
+   * @param {string} memoryId
+   * @param {string} hash
+   * @param {Object} payload - Update fields (content, category, etc.)
+   * @returns {Promise<{ok: boolean, hash: string}>}
+   */
+  async memoryWriteExpecting(memoryId, hash, payload) {
+    if (!hash) throw new Error('oceum: memoryWriteExpecting requires a hash from memoryReadWithHash');
+    const res = await this.#sendWithHeaders('memory_update', { memoryId, ...payload }, { 'If-Match': hash });
+    return { ok: true, hash: res.version_hash };
+  }
+
+  /**
+   * Read an integration entry along with its version_hash.
+   * @param {string} integrationId
+   * @returns {Promise<{data: Object, hash: string}>}
+   */
+  async integrationReadWithHash(integrationId) {
+    const res = await this.#send('integration_read', { integrationId });
+    return { data: res.integration, hash: res.integration && res.integration.version_hash };
+  }
+
+  /**
+   * Write an integration entry expecting the row to currently match `hash`.
+   * Throws OceumConflictError on hash mismatch (409). Does NOT retry on 409.
+   * @param {string} integrationId
+   * @param {string} hash
+   * @param {Object} payload - Update fields (config, status, agentTypes, etc.)
+   * @returns {Promise<{ok: boolean, hash: string}>}
+   */
+  async integrationWriteExpecting(integrationId, hash, payload) {
+    if (!hash) throw new Error('oceum: integrationWriteExpecting requires a hash from integrationReadWithHash');
+    const res = await this.#sendWithHeaders('integration_update', { integrationId, ...payload }, { 'If-Match': hash });
+    return { ok: true, hash: res.version_hash };
+  }
+
   // ── Getters ────────────────────────────────────────
 
   get agentId() { return this.#agentId; }
   get baseUrl() { return this.#baseUrl; }
 }
 
-module.exports = { Oceum, OceumError };
+module.exports = { Oceum, OceumError, OceumConflictError };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oceum",
-  "version": "0.3.0",
-  "description": "Official SDK for Oceum — governed agent infrastructure. Progressive autonomy, zero-knowledge vault, governed execution, and enterprise-grade observability.",
+  "version": "0.5.0",
+  "description": "Official SDK for Oceum — governed agent infrastructure. Progressive autonomy, blind-relay vault (the agent never sees the secret), governed execution, and enterprise-grade observability.",
   "main": "index.js",
   "types": "index.d.ts",
   "exports": {