@mnemosyne_os/sdk 1.0.0 → 1.2.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/client.ts
-import WebSocket from "ws";
+import WebSocket2 from "ws";
 
 // src/manifest.ts
 import { z } from "zod";
@@ -14,13 +14,30 @@ var VALID_SCOPES = [
   "vault:write:PERSONAL",
   "vault:read:FINANCE",
   "vault:write:FINANCE",
-  "vault:read:COOK",
-  "vault:write:COOK",
+  "vault:read:RESEARCH",
+  "vault:write:RESEARCH",
+  /** Wildcard: grants r/w to any user-created custom vault. */
+  "vault:read:CUSTOM",
+  "vault:write:CUSTOM",
   "share:request",
-  "share:grant"
+  "share:grant",
+  "monorepo:read",
+  "agents:read",
+  "nft:validate",
+  "neural:graph:read",
+  "llm:query",
+  // [PHASE-58] Read-only access to Perpetual Memory Bridges
+  "bridge:read"
 ];
-var VALID_INTENTS = ["INGEST", "QUERY", "CORRELATE", "FORGET"];
-var VALID_VAULTS = ["DEV", "SOCIAL", "PERSONAL", "FINANCE", "COOK"];
+var GRANT_REQUIRED_SCOPE_PREFIXES = [
+  "vault:read:",
+  "vault:write:",
+  "share:request",
+  "share:grant",
+  "llm:query"
+];
+var VALID_INTENTS = ["INGEST", "QUERY", "CORRELATE", "FORGET", "GIT_LOG", "LIST_AGENTS", "LIST_VAULTS", "BRIDGE_READ"];
+var VALID_VAULTS = ["DEV", "SOCIAL", "PERSONAL", "FINANCE", "RESEARCH"];
 var SEMVER_RE = /^\d+\.\d+\.\d+/;
 var APP_ID_RE = /^[a-z0-9][a-z0-9_-]{1,63}$/;
 var AppManifestSchema = z.object({
@@ -36,12 +53,22 @@ var AppManifestSchema = z.object({
   scopes: z.array(z.enum(VALID_SCOPES)).min(1, {
     message: "At least one scope required \u2014 apps with no scopes have no access"
   }),
-  vaults: z.array(z.enum(VALID_VAULTS)).min(1),
+  /**
+   * Vaults the app can access.
+   * Core vaults must use the built-in identifiers (DEV, SOCIAL, etc.).
+   * Custom vault IDs are opaque uppercase strings — the manifest may list them
+   * here to pre-declare intent, and the OS validates them at runtime.
+   */
+  vaults: z.array(z.union([z.enum(VALID_VAULTS), z.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/, "Custom vault ID must be UPPER_SNAKE_CASE")])).min(1),
   intents: z.array(z.enum(VALID_INTENTS)).min(1),
   max_chronicle_size_kb: z.number().int().min(1).max(1024).optional().default(64),
+  /**
+   * @deprecated Remplacé par requiresOsGrant() — ce flag n'a aucun effet sur la sécurité.
+   * L'OS décide toujours en fonction des scopes déclarés (MN-004).
+   */
   requires_consent: z.boolean().optional().default(false),
   description: z.string().max(256).optional()
-}).strict();
+});
 function loadManifest(pathOrManifest) {
   if (typeof pathOrManifest === "string") {
     const absPath = resolve(pathOrManifest);
@@ -65,6 +92,12 @@ ${issues}`);
   return result.data;
 }
 function assertScope(manifest, scope) {
+  if (scope.startsWith("vault:read:") && !["DEV", "SOCIAL", "PERSONAL", "FINANCE", "RESEARCH"].includes(scope.split(":")[2] ?? "")) {
+    if (manifest.scopes.includes("vault:read:CUSTOM")) return;
+  }
+  if (scope.startsWith("vault:write:") && !["DEV", "SOCIAL", "PERSONAL", "FINANCE", "RESEARCH"].includes(scope.split(":")[2] ?? "")) {
+    if (manifest.scopes.includes("vault:write:CUSTOM")) return;
+  }
   if (!manifest.scopes.includes(scope)) {
     throw new Error(
       `[MnemoSDK] Scope "${scope}" not declared in manifest for app "${manifest.id}". Add it to manifest.scopes to request this permission.`
@@ -78,15 +111,37 @@ function assertVault(manifest, vault) {
     );
   }
 }
+function requiresOsGrant(manifest) {
+  return manifest.scopes.some(
+    (scope) => GRANT_REQUIRED_SCOPE_PREFIXES.some((prefix) => scope.startsWith(prefix))
+  );
+}
 
 // src/jwt.ts
 import { createHmac, randomBytes, timingSafeEqual } from "crypto";
 function b64url(input) {
-  const buf = typeof input === "string" ? Buffer.from(input, "utf8") : input;
-  return buf.toString("base64url");
+  if (typeof Buffer !== "undefined" && typeof Buffer.alloc(0).toString("base64url") === "string") {
+    try {
+      const buf = typeof input === "string" ? Buffer.from(input, "utf8") : Buffer.from(input);
+      return buf.toString("base64url");
+    } catch {
+    }
+  }
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  let b64 = "";
+  if (typeof btoa !== "undefined") {
+    b64 = btoa(String.fromCharCode(...Array.from(bytes)));
+  } else {
+    b64 = Buffer.from(bytes).toString("base64");
+  }
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 function parseB64url(input) {
-  return Buffer.from(input, "base64url").toString("utf8");
+  const base64 = input.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - input.length % 4) % 4);
+  if (typeof atob !== "undefined") {
+    return decodeURIComponent(escape(atob(base64)));
+  }
+  return Buffer.from(base64, "base64").toString("utf8");
 }
 var HEADER = b64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
 function signToken(payload, secret) {
@@ -199,8 +254,8 @@ var MnemoClient = class _MnemoClient {
   }
   _connectWs() {
     return new Promise((resolve2, reject) => {
-      const url = `ws://localhost:${this.options.wsPort}`;
-      this.ws = new WebSocket(url);
+      const url = `ws://127.0.0.1:${this.options.wsPort}`;
+      this.ws = new WebSocket2(url);
       const timeout = setTimeout(() => {
         this.ws?.terminate();
         reject(new Error(`[MnemoSDK] Connection timeout to ${url}`));
@@ -249,7 +304,7 @@ var MnemoClient = class _MnemoClient {
   }
   _rpcWs(method, params) {
     return new Promise((resolve2, reject) => {
-      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      if (!this.ws || this.ws.readyState !== WebSocket2.OPEN) {
         return reject(new Error("[MnemoSDK] WebSocket not open"));
       }
       const id = Math.random().toString(36).slice(2);
@@ -349,7 +404,13 @@ var MnemoClient = class _MnemoClient {
       text,
       vault,
       limit: options.limit ?? 10,
-      threshold: options.threshold ?? 0
+      threshold: options.threshold ?? 0,
+      // [SDK 1.2 — Semantic Bridge] Forward opt-in semantic params. Server
+      // ignores absent fields, so omitting these preserves legacy "recent"
+      // behaviour exactly.
+      ...options.semantic !== void 0 ? { semantic: options.semantic } : {},
+      ...options.scope !== void 0 ? { scope: options.scope } : {},
+      ...options.spineTypeFilter !== void 0 ? { spineTypeFilter: options.spineTypeFilter } : {}
     });
   }
   /**
@@ -407,25 +468,55 @@ var MnemoClient = class _MnemoClient {
   get appManifest() {
     return { ...this.manifest };
   }
-  /** Inspecte le token actuel (décodé, sans vérification) */
+  /**
+   * Inspecte le token actuel (décodé, sans vérification cryptographique).
+   * Utilise un décodeur base64url universel (Node + Browser) — MN-005.
+   */
   get tokenInfo() {
     if (!this.token) return null;
     try {
       const [, payloadB64] = this.token.split(".");
       if (!payloadB64) return null;
-      return JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
+      const base64 = payloadB64.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - payloadB64.length % 4) % 4);
+      const json = typeof atob !== "undefined" ? decodeURIComponent(escape(atob(base64))) : Buffer.from(base64, "base64").toString("utf8");
+      return JSON.parse(json);
     } catch {
       return null;
     }
   }
+  /**
+   * [PHASE-50] Lit un fichier .md depuis le repo OS (docs/, packages/).
+   */
+  async readFile(path) {
+    const res = await this._rpc("sdk.readFile", { path });
+    return res.content;
+  }
+  /**
+   * Returns the most recent git commits from the OS monorepo.
+   * Calls the server-side `sdk.git.log` RPC (repo path is hardcoded server-side
+   * for Zero-Trust — the client cannot choose it).
+   * Requires scope `monorepo:read` and intent `GIT_LOG` in the manifest.
+   */
+  async gitLog(options = {}) {
+    assertScope(this.manifest, "monorepo:read");
+    if (!this.manifest.intents.includes("GIT_LOG")) {
+      throw new Error('[MnemoSDK] Intent "GIT_LOG" not declared in manifest');
+    }
+    return this._rpc("sdk.git.log", {
+      appId: this.manifest.id,
+      limit: options.limit ?? 20,
+      since: options.since,
+      filter: options.filter
+    });
+  }
 };
 
 // src/constants.ts
 var MNEMOSYNE_METHODS = {
-  // ── Auth ──────────────────────────────────────────────────────────────────
+  // ── Auth ───────────────────────────────────────────────────────────────
   /** Enregistre l'app, valide le manifest, retourne un JWT 24h */
   REGISTER: "sdk.register",
-  // ── Vault ─────────────────────────────────────────────────────────────────
+  // ── Vault ───────────────────────────────────────────────────────────────
   /** Ingère du contenu dans le vault (vectorisation incluse) */
   INGEST: "sdk.ingest",
   /** Requête sémantique — résultats filtrés par source_app_id */
@@ -434,22 +525,84 @@ var MNEMOSYNE_METHODS = {
   CORRELATE: "sdk.correlate",
   /** Supprime un chronicle par ID (scope vault:write requis) */
   FORGET: "sdk.forget",
-  // ── Cross-App ─────────────────────────────────────────────────────────────
+  // ── Resonances ───────────────────────────────────────────────────────────
+  /**
+   * Liste les Resonances actives (projets cognitifs) depuis le vault DEV.
+   * Requiert le scope `vault:read:DEV`.
+   */
+  RESONANCES_LIST: "sdk.resonances.list",
+  /**
+   * Met à jour la position courante d'une Resonance (phase, description).
+   * Persisté comme chronicle DECISION dans le vault DEV.
+   * Requiert le scope `vault:write:DEV`.
+   */
+  UPDATE_POSITION: "sdk.resonance.updatePosition",
+  // ── Monorepo ───────────────────────────────────────────────────────────
+  /**
+   * Lit le git log du monorepo Mnemosyne OS.
+   * Requiert le scope `monorepo:read` dans le manifest.
+   * Retourne les commits filtrés (hash, message, author, date).
+   * [SECURITY] Path hardcodé côté serveur — le client ne contrôle pas le repo.
+   */
+  GIT_LOG: "sdk.git.log",
+  /**
+   * Lit un fichier .md depuis le repo Mnemosyne OS (docs/, packages/).
+   * Requiert le scope `monorepo:read`.
+   * [SECURITY] Seuls les .md sont lisibles, path sanitizé côté serveur.
+   */
+  READ_FILE: "sdk.readFile",
+  // ── Agents ───────────────────────────────────────────────────────────────
+  /**
+   * Liste les agents actifs connectés au SDK WebSocket Server.
+   * Requiert le scope `agents:read` dans le manifest.
+   */
+  LIST_AGENTS: "sdk.agents.list",
+  // ── Cross-App ──────────────────────────────────────────────────────────
   /** Demande d'accès aux chronicles d'une autre app (popup consentement) */
   SHARE: "sdk.share",
-  // ── NFT Licence ───────────────────────────────────────────────────────────
+  // ── NFT Licence ─────────────────────────────────────────────────────────
   /**
    * Vérifie qu'un wallet possède le NFT de licence de cette app.
    * Requiert le scope `nft:validate` dans le manifest.
    * Cache TTL 5 min côté OS pour ne pas spam la blockchain.
    */
   NFT_VALIDATE: "sdk.nft.validate",
-  // ── NeuralGraph ───────────────────────────────────────────────────────────
+  // ── NeuralGraph ─────────────────────────────────────────────────────────
+  /**
+   * Queries the NeuralGraph — returns nodes and edges near the given text.
+   * Requires scope `neural:graph:read`.
+   */
+  GRAPH_QUERY: "sdk.graph.query",
+  // ── Vault Discovery ─────────────────────────────────────────────────────
   /**
-   * Requête le NeuralGraph — retourne les nœuds et arêtes proches du texte.
-   * Requiert le scope `neural:graph:read` dans le manifest.
+   * Lists all available vaults (core built-ins + user-created custom vaults).
+   * Requires intent `LIST_VAULTS`.
+   * Returns `VaultListResult` with `coreVaults` and `customVaults` arrays.
+   * Use the `id` field of each vault as the `vault` param in ingest/query.
    */
-  GRAPH_QUERY: "sdk.graph.query"
+  LIST_VAULTS: "sdk.vaults.list",
+  // ── Correlate ─────────────────────────────────────────────────────────
+  // (CORRELATE and FORGET are already declared in the Vault section above)
+  // ── Forget (GDPR) ────────────────────────────────────────────────────────
+  // (See FORGET above)
+  // ── Dynamic Spine Registry ────────────────────────────────────────────────
+  /**
+   * Allocates a new dynamic spine in the OS neural registry (Protocole du Guichet).
+   * Requires scope `vault:write:CUSTOM`.
+   * The allocated spine appears in the Mnemosyne OS neural graph.
+   */
+  REGISTER_SPINE: "sdk.spine.register",
+  /**
+   * Releases a previously allocated dynamic spine.
+   * Only the owning app can release its own spines.
+   * Requires scope `vault:write:CUSTOM`.
+   */
+  RELEASE_SPINE: "sdk.spine.release",
+  /**
+   * Lists all currently allocated dynamic spines across all registered apps.
+   * Returns an array of `DynamicSpineInfo` objects.
+   */
+  LIST_SPINES: "sdk.spine.list"
 };
 var MNEMOSYNE_WS_PORT = 7799;
 var MNEMOSYNE_WS_HOST = "127.0.0.1";
@@ -460,8 +613,414 @@ var MNEMOSYNE_CHAINS = {
   POLYGON: { id: 137, name: "Polygon", rpc: "https://polygon-rpc.com" },
   BASE_SEPOLIA: { id: 84532, name: "Base Sepolia (testnet)", rpc: "https://sepolia.base.org" }
 };
+
+// src/browser-client.ts
+var MnemoClientBrowser = class _MnemoClientBrowser {
+  ws;
+  token = null;
+  pending = /* @__PURE__ */ new Map();
+  _onPush;
+  _onDisconnect;
+  timeoutMs;
+  constructor(ws, timeoutMs) {
+    this.ws = ws;
+    this.timeoutMs = timeoutMs;
+    this.ws.onmessage = (e) => this._handleMsg(e.data);
+    this.ws.onclose = () => {
+      this._onDisconnect?.();
+      for (const [, p] of this.pending) {
+        clearTimeout(p.timer);
+        p.reject(new Error("[MnemoClientBrowser] WebSocket disconnected"));
+      }
+      this.pending.clear();
+    };
+  }
+  // ── Static factory ───────────────────────────────────────────────────────────
+  /**
+   * Crée une connexion WebSocket native vers le SDK server de Mnemosyne OS.
+   *
+   * @param host - Hostname du SDK server (défaut: '127.0.0.1')
+   * @param port - Port du SDK server (défaut: 7799)
+   * @param timeoutMs - Timeout de chaque RPC en ms (défaut: 15000)
+   */
+  static connect(host = MNEMOSYNE_WS_HOST, port = MNEMOSYNE_WS_PORT, timeoutMs = 15e3) {
+    return new Promise((resolve2, reject) => {
+      const url = `ws://${host}:${port}`;
+      const ws = new WebSocket(url);
+      const timeout = setTimeout(() => {
+        ws.close();
+        reject(new Error(`[MnemoClientBrowser] Connection timeout to ${url}`));
+      }, timeoutMs);
+      ws.onopen = () => {
+        clearTimeout(timeout);
+        resolve2(new _MnemoClientBrowser(ws, timeoutMs));
+      };
+      ws.onerror = () => {
+        clearTimeout(timeout);
+        reject(new Error(`[MnemoClientBrowser] Failed to connect to ${url} \u2014 is Mnemosyne OS running?`));
+      };
+    });
+  }
+  // ── Message router ───────────────────────────────────────────────────────────
+  _handleMsg(raw) {
+    try {
+      const msg = JSON.parse(raw);
+      if (msg.push && msg.event) {
+        this._onPush?.(msg.event);
+        return;
+      }
+      const p = this.pending.get(msg.id);
+      if (!p) return;
+      clearTimeout(p.timer);
+      this.pending.delete(msg.id);
+      if (msg.error) p.reject(new Error(msg.error));
+      else p.resolve(msg.result);
+    } catch {
+    }
+  }
+  // ── Low-level RPC ────────────────────────────────────────────────────────────
+  call(method, params) {
+    return new Promise((resolve2, reject) => {
+      if (this.ws.readyState !== WebSocket.OPEN) {
+        return reject(new Error("[MnemoClientBrowser] WebSocket not open"));
+      }
+      const id = Math.random().toString(36).slice(2);
+      const req = {
+        id,
+        method,
+        params,
+        ...this.token ? { token: this.token } : {}
+      };
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`[MnemoClientBrowser] RPC timeout: ${method} (${this.timeoutMs}ms)`));
+      }, this.timeoutMs);
+      this.pending.set(id, {
+        resolve: (v) => resolve2(v),
+        reject,
+        timer
+      });
+      this.ws.send(JSON.stringify(req));
+    });
+  }
+  // ── Auth ─────────────────────────────────────────────────────────────────────
+  /**
+   * Enregistre l'app auprès de Mnemosyne OS et obtient un JWT 24h.
+   * Doit être appelé avant toute autre méthode.
+   *
+   * @throws si le manifest est invalide ou si l'OS refuse l'enregistrement
+   */
+  async register(manifest) {
+    const res = await this.call("sdk.register", { manifest });
+    this.token = res.token;
+    return res;
+  }
+  // ── Vault ─────────────────────────────────────────────────────────────────────
+  /**
+   * Ingère du contenu dans le vault Mnemosyne.
+   * Le contenu est vectorisé par le runtime OS (pas dans le SDK).
+   * Requiert le scope `vault:write:<vault>` et l'intent `INGEST`.
+   */
+  async ingest(content, spineType, vault = "DEV", metadata) {
+    const res = await this.call("sdk.ingest", {
+      appId: this.appId ?? "unknown",
+      content,
+      spineType,
+      vault,
+      ...metadata ? { metadata } : {}
+    });
+    return res;
+  }
+  /**
+   * Requête sémantique sur le vault — retourne les chronicles les plus proches.
+   * Requiert le scope `vault:read:<vault>` et l'intent `QUERY`.
+   *
+   * @param text    - Texte de recherche
+   * @param vault   - Vault cible (défaut: 'DEV')
+   * @param limit   - Nombre max de résultats (défaut: 10)
+   * @param options - [SDK 1.2] Options sémantiques additionnelles (semantic,
+   *                  scope, spineTypeFilter). Voir {@link QueryOptions}.
+   */
+  async query(text, vault = "DEV", limit = 10, options = {}) {
+    const res = await this.call("sdk.query", {
+      appId: this.appId ?? "unknown",
+      text,
+      vault,
+      limit,
+      // [SDK 1.2 — Semantic Bridge] Forward optional semantic params.
+      ...options.semantic !== void 0 ? { semantic: options.semantic } : {},
+      ...options.scope !== void 0 ? { scope: options.scope } : {},
+      ...options.spineTypeFilter !== void 0 ? { spineTypeFilter: options.spineTypeFilter } : {}
+    });
+    if (!res.success) throw new Error(res.error ?? "query failed");
+    return res.chronicles ?? [];
+  }
+  // ── Resonances ────────────────────────────────────────────────────────────────
+  /**
+   * Returns the active Resonances (cognitive projects) from the DEV vault.
+   * Requires scope `vault:read:DEV`.
+   */
+  async resonancesList() {
+    const res = await this.call(
+      "sdk.resonances.list",
+      { appId: this.appId ?? "unknown" }
+    );
+    return res.success ? res.resonances ?? [] : [];
+  }
+  /**
+   * Persists the current position of a Resonance in the DEV vault.
+   * Requires scope `vault:write:DEV`.
+   *
+   * @param resonanceId - Resonance identifier
+   * @param position    - Current position description (e.g. 'Phase 51.2 — auto-poll')
+   * @param phase       - Current phase (e.g. 'Phase 51')
+   */
+  async updatePosition(resonanceId, position, phase) {
+    return this.call("sdk.resonance.updatePosition", {
+      appId: this.appId ?? "unknown",
+      resonanceId,
+      position,
+      phase
+    });
+  }
+  // ── Monorepo ──────────────────────────────────────────────────────────────────
+  /**
+   * Retourne les commits récents du monorepo Mnemosyne OS.
+   * Requiert le scope `monorepo:read` et l'intent `GIT_LOG`.
+   * [SECURITY] Le chemin du repo est hardcodé côté serveur.
+   *
+   * @param limit - Nombre de commits max (défaut: 20)
+   * @param since - Date relative Git (ex: '30 days ago', '2024-01-01')
+   */
+  async gitLog(limit = 20, since) {
+    const res = await this.call(
+      "sdk.git.log",
+      { appId: this.appId ?? "unknown", limit, since }
+    );
+    return res.success ? res.commits ?? [] : [];
+  }
+  /**
+   * Lit un fichier `.md` depuis le repo Mnemosyne OS.
+   * Requiert le scope `monorepo:read`.
+   * [SECURITY] Seuls les fichiers `.md` sont accessibles, path sanitizé côté serveur.
+   *
+   * @param path - Chemin relatif au repo (ex: 'docs/ARCHITECTURE.md')
+   */
+  async readFile(path) {
+    const res = await this.call("sdk.readFile", { path });
+    return res.content ?? "";
+  }
+  // ── Agents ──────────────────────────────────────────────────────────────────────
+  /**
+   * Lists Layer 2 apps currently connected to the SDK WebSocket Server.
+   * Requires scope `agents:read` and intent `LIST_AGENTS`.
+   */
+  async agentsList() {
+    const res = await this.call(
+      "sdk.agents.list",
+      { appId: this.appId ?? "unknown" }
+    );
+    return res.success ? res.agents ?? [] : [];
+  }
+  // ── Vault Discovery [v1.2.0] ────────────────────────────────────────────────────
+  /**
+   * Returns all available vaults (core built-ins + user-created custom vaults).
+   * Use the `id` field of each entry as the `vault` param in `ingest()` and `query()`.
+   * Requires intent `LIST_VAULTS`.
+   */
+  async vaultsList() {
+    return this.call("sdk.vaults.list", { appId: this.appId ?? "unknown" });
+  }
+  // ── Correlate [v1.2.0] ──────────────────────────────────────────────────────────
+  /**
+   * Finds chronicles causally or semantically linked to a source chronicle.
+   * Requires intent `CORRELATE` and the appropriate vault read scope.
+   *
+   * @param options - `{ sourceId, vault?, limit?, threshold? }`
+   */
+  async correlate(options) {
+    return this.call("sdk.correlate", {
+      appId: this.appId ?? "unknown",
+      ...options
+    });
+  }
+  // ── Forget / GDPR [v1.2.0] ──────────────────────────────────────────────────────
+  /**
+   * Permanently deletes a chronicle by ID. Requires intent `FORGET`
+   * and the appropriate vault write scope.
+   *
+   * @param chronicleId - ID of the chronicle to delete.
+   * @param vault       - Vault to delete from (default: 'DEV').
+   */
+  async forget(chronicleId, vault = "DEV") {
+    return this.call("sdk.forget", {
+      appId: this.appId ?? "unknown",
+      chronicleId,
+      vault
+    });
+  }
+  // ── NeuralGraph [v1.2.0] ────────────────────────────────────────────────────────
+  /**
+   * Queries the NeuralGraph — returns nodes and edges near the given text.
+   * Requires scope `neural:graph:read`.
+   *
+   * @param text      - Search text to embed and match against the graph.
+   * @param threshold - Minimum edge strength 0-1 (default: 0.5).
+   */
+  async graphQuery(text, threshold = 0.5) {
+    return this.call("sdk.graph.query", {
+      appId: this.appId ?? "unknown",
+      text,
+      threshold
+    });
+  }
+  // ── Dynamic Spine Registry [v1.2.0] ──────────────────────────────────────────────
+  /**
+   * Allocates a new dynamic spine in the OS Protocole du Guichet registry.
+   * Requires scope `vault:write:CUSTOM`.
+   *
+   * @example
+   * ```ts
+   * await client.spineRegister({
+   *   id: 'my_events', name: 'App Events', type: 'SESSION', icon: '📊'
+   * });
+   * ```
+   */
+  async spineRegister(spine) {
+    return this.call("sdk.spine.register", {
+      appId: this.appId ?? "unknown",
+      spine
+    });
+  }
+  /**
+   * Releases a dynamic spine previously allocated by this app.
+   * Requires scope `vault:write:CUSTOM`.
+   */
+  async spineRelease(spineId) {
+    return this.call("sdk.spine.release", {
+      appId: this.appId ?? "unknown",
+      spineId
+    });
+  }
+  /**
+   * Lists all currently allocated dynamic spines across all apps.
+   */
+  async spineList() {
+    const res = await this.call(
+      "sdk.spine.list",
+      { appId: this.appId ?? "unknown" }
+    );
+    return res.success ? res.spines ?? [] : [];
+  }
+  // ── [PHASE-58] Perpetual Memory Bridges [v2.0] ───────────────────────────────────────
+  /**
+   * Returns the persistent semantic bridges stored in the user's vault.
+   * Bridges are cognitive links discovered by Semantic Reflect scans between
+   * cross-vault chronicles (e.g. SOCIAL ⇔ DEV, PERSONAL ⇔ DEV).
+   *
+   * [PHASE-58][PLATFORM][READ-ONLY]
+   *
+   * Required manifest: `scopes: ['bridge:read']`, `intents: ['BRIDGE_READ']`
+   *
+   * @param options - Optional filters: `{ limit, since, minCosine, vaultFilter, onlyNew }`
+   *
+   * @example
+   * ```typescript
+   * const result = await client.getBridgeHistory({ minCosine: 0.80, limit: 50 });
+   * console.log(`${result.bridges.length} high-confidence bridges`);
+   * ```
+   */
+  async getBridgeHistory(options) {
+    return this.call("sdk.bridges.history", {
+      appId: this.appId ?? "unknown",
+      ...options
+    });
+  }
+  /**
+   * Computes a resonance score for a text against the user's bridge history.
+   * Use this to measure cognitive relevance before publishing a social post.
+   *
+   * [PHASE-58][PLATFORM][READ-ONLY]
+   *
+   * Required manifest: `scopes: ['bridge:read']`, `intents: ['BRIDGE_READ']`
+   *
+   * @param text - Text to score (e.g. LinkedIn/Reddit post draft).
+   * @param topK - Number of top matches to return (default: 5).
+   *
+   * @returns { score: 0-1, level: 'LOW'|'MEDIUM'|'HIGH_RESONANCE', topMatches }
+   *
+   * @example
+   * ```typescript
+   * const score = await client.computeResonance(postDraft, 5);
+   * if (score.level === 'HIGH_RESONANCE') {
+   *   console.log('✨ This post aligns with your cognitive graph!');
+   * }
+   * ```
+   */
+  async computeResonance(text, topK = 5) {
+    return this.call("sdk.bridges.resonance", {
+      appId: this.appId ?? "unknown",
+      text,
+      topK
+    });
+  }
+  // ── Events ────────────────────────────────────────────────────────────────────
+  /**
+   * Enregistre un handler pour les push events envoyés par l'OS.
+   * Déclenché par exemple quand un autre client ingère un chronicle (`chronicle:new`).
+   *
+   * @example
+   * ```typescript
+   * client.onPush((event) => {
+   *   if (event.type === 'chronicle:new') {
+   *     console.log('New chronicle from:', event.sourceApp);
+   *   }
+   * });
+   * ```
+   */
+  onPush(fn) {
+    this._onPush = fn;
+  }
+  /**
+   * Enregistre un callback appelé quand la connexion WS est fermée par l'OS.
+   */
+  onDisconnect(fn) {
+    this._onDisconnect = fn;
+  }
+  // ── Lifecycle ─────────────────────────────────────────────────────────────────
+  /**
+   * Ferme la connexion WebSocket proprement.
+   */
+  close() {
+    this.ws.close(1e3, "Client close");
+  }
+  // ── Getters ───────────────────────────────────────────────────────────────────
+  get isConnected() {
+    return this.ws.readyState === WebSocket.OPEN;
+  }
+  /** Token JWT actuel (null avant register()) */
+  get currentToken() {
+    return this.token;
+  }
+  /**
+   * AppId extrait du JWT actuel, ou null si non enregistré.
+   */
+  get appId() {
+    if (!this.token) return null;
+    try {
+      const [, b64] = this.token.split(".");
+      if (!b64) return null;
+      const padded = b64.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - b64.length % 4) % 4);
+      const payload = JSON.parse(atob(padded));
+      return payload.sub ?? null;
+    } catch {
+      return null;
+    }
+  }
+};
 export {
   AppManifestSchema,
+  GRANT_REQUIRED_SCOPE_PREFIXES,
   MNEMOSYNE_CHAINS,
   MNEMOSYNE_METHODS,
   MNEMOSYNE_NFT_CACHE_TTL_MS,
@@ -469,11 +1028,13 @@ export {
   MNEMOSYNE_WS_HOST,
   MNEMOSYNE_WS_PORT,
   MnemoClient,
+  MnemoClientBrowser,
   assertScope,
   assertVault,
   generateAppToken,
   generateSecret,
   loadManifest,
   parseManifest,
+  requiresOsGrant,
   verifyToken
 };