@mnemosyne_os/sdk 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,29 +1,63 @@
 import { z } from 'zod';
 
 /**
- * @mnemosyne/sdk — Public Types
+ * @mnemosyne_os/sdk — Public Types
  *
- * Ce fichier est la surface publique du SDK.
- * Toute modification ici constitue un changement de contrat API.
+ * This file is the public API contract surface of the SDK.
+ * Any modification here constitutes a breaking or additive API change.
+ *
+ * Version history:
+ *   v1.1.0 — initial types (ingest, query, git, agents, NFT, NeuralGraph)
+ *   v1.2.0 — custom vault support, Resonance types, Correlate/Forget/DynamicSpine API
  *
  * [SDK][ZERO-TRUST][AUDIT-TRAIL]
  */
-/** Scopes disponibles pour une app tierce */
-type MnemoScope = 'vault:read:DEV' | 'vault:write:DEV' | 'vault:read:SOCIAL' | 'vault:write:SOCIAL' | 'vault:read:PERSONAL' | 'vault:write:PERSONAL' | 'vault:read:FINANCE' | 'vault:write:FINANCE' | 'vault:read:COOK' | 'vault:write:COOK' | 'share:request' | 'share:grant'
-/** Accès en lecture au git log du monorepo Mnemosyne OS */
+/**
+ * All available permission scopes for a Layer 2 application.
+ *
+ * Scopes follow the pattern `resource:action:target`.
+ * Any scope not listed here is silently refused by the Zero-Trust gate.
+ *
+ * **Custom vault scopes:**
+ * Use `vault:read:CUSTOM` / `vault:write:CUSTOM` to request read/write access
+ * to any custom vault created by the user. The actual vault ID is resolved at
+ * runtime from the `vaults` field of the manifest.
+ */
+type MnemoScope = 'vault:read:DEV' | 'vault:write:DEV' | 'vault:read:SOCIAL' | 'vault:write:SOCIAL' | 'vault:read:PERSONAL' | 'vault:write:PERSONAL' | 'vault:read:FINANCE' | 'vault:write:FINANCE' | 'vault:read:RESEARCH' | 'vault:write:RESEARCH'
+/** Wildcard scope — grants read access to any user-created custom vault. */
+ | 'vault:read:CUSTOM'
+/** Wildcard scope — grants write access to any user-created custom vault. */
+ | 'vault:write:CUSTOM' | 'share:request' | 'share:grant'
+/** Read access to the Mnemosyne OS monorepo git log. */
  | 'monorepo:read'
-/** Liste les agents SDK connectés */
+/** List active connected SDK agents. */
  | 'agents:read'
-/** Validation de licence NFT on-chain pour MnemoStore */
+/** On-chain NFT licence validation for MnemoStore. Premium scope. */
  | 'nft:validate'
-/** Accès en lecture au NeuralGraph (nœuds, arêtes, clusters) */
+/** Read access to the NeuralGraph (nodes, edges, clusters). */
  | 'neural:graph:read'
-/** Requêtes LLM directes via le runtime Mnemosyne — scope premium */
- | 'llm:query';
-/** Intents IPC autorisés dans le manifest */
-type MnemoIntent = 'INGEST' | 'QUERY' | 'CORRELATE' | 'FORGET' | 'GIT_LOG' | 'LIST_AGENTS';
-/** Vault cible */
-type MnemoVault = 'DEV' | 'SOCIAL' | 'PERSONAL' | 'FINANCE' | 'COOK';
+/** Direct LLM queries via the Mnemosyne runtime. Premium scope. */
+ | 'llm:query'
+/**
+ * [PHASE-58] Read access to the Perpetual Memory Bridges.
+ * Allows a Layer 2 app to call getBridgeHistory() and computeResonance().
+ * Write access (saveBridges) is CORE-ONLY and not exposed to Layer 2.
+ */
+ | 'bridge:read';
+/**
+ * Allowed IPC intents for a Layer 2 application.
+ * An intent is the high-level operation the app is permitted to perform.
+ * Each intent maps to one or more WS server routes.
+ */
+type MnemoIntent = 'INGEST' /** Write content to a vault (triggers vectorization). */ | 'QUERY' /** Semantic search against a vault. */ | 'CORRELATE' /** Find causal/temporal/semantic links between chronicles. */ | 'FORGET' /** Delete a chronicle by ID (GDPR). */ | 'GIT_LOG' /** Read the monorepo git commit log. */ | 'LIST_AGENTS' /** List active SDK agents connected to the WS server. */ | 'LIST_VAULTS' /** Discover available vaults (core + custom). */ | 'BRIDGE_READ'; /** [PHASE-58] Read bridge history and compute resonance scores. */
+/**
+ * Target vault identifier.
+ *
+ * Core vaults are fixed string literals.
+ * Custom vaults created via Phase 41 are identified by an opaque uppercase string ID
+ * (e.g. `'MY_NOTES'`). Discover available custom vault IDs via `sdk.vaults.list`.
+ */
+type MnemoVault = 'DEV' | 'SOCIAL' | 'PERSONAL' | 'FINANCE' | 'RESEARCH' | (string & {});
 /** Types de spine sémantiques */
 type SpineType = 'GIT' | 'ARCHITECTURE' | 'DECISION' | 'DEBUG' | 'FEATURE' | 'REDDIT_POST' | 'LINKEDIN_POST' | 'SOCIAL_NODE' | 'DOCUMENT' | 'NOTE' | 'CUSTOM'
 /** Créé par le Cockpit ou via sdk.resonances.list */
@@ -31,9 +65,9 @@ type SpineType = 'GIT' | 'ARCHITECTURE' | 'DECISION' | 'DEBUG' | 'FEATURE' | 'RE
 /** Persistance de session / contexte de reprise */
  | 'SESSION'
 /** Mise à jour de position (phase, état courant) */
- | 'POSITION_UPDATE'
-/** Documentation API ou spec */
- | 'API' | 'DOC' | 'ERROR';
+ | 'POSITION_UPDATE' | 'API' | 'DOC' | 'ERROR'
+/** [PHASE-64] Affective & Ideational Spines */
+ | 'EPIPHANY' | 'EMOTIONAL' | 'TENSION' | 'FLOW' | 'IDEATIONAL' | 'HYPOTHESIS' | 'CONCERN' | 'VISION' | 'CONTEXTUAL' | 'DISCOVERY' | (string & {});
 /** Manifest de l'application — fichier `app.manifest.json` */
 interface AppManifest {
     /** Identifiant unique stable de l'app (snake_case recommandé) */
@@ -107,6 +141,34 @@ interface QueryOptions {
     vault?: MnemoVault;
     /** Seuil de similarité minimum 0-1 (défaut: 0.0) */
     threshold?: number;
+    /**
+     * [SDK 1.2 — Semantic Bridge] Opt-in true semantic ranking.
+     *
+     * When `false` / omitted, the server returns the N most recent chronicles
+     * (the Cockpit fast-path, ~5ms, query text ignored).
+     *
+     * When `true`, the server embeds the query via the host's active model
+     * (Vertex 768D / e5-base / Hybrid) and ranks via `querySemanticContext`
+     * with cosine similarity × spineType weight under the cognitive `scope`.
+     *
+     * Use `true` for agent-style queries where relevance matters more than
+     * recency. Default behaviour stays "recent" to preserve historical
+     * contracts (notably Cockpit's live feed).
+     */
+    semantic?: boolean;
+    /**
+     * [SDK 1.2] Cognitive ranking scope for type-weighting. Only meaningful
+     * when `semantic: true`. Defaults to `'SOURCE_CODE'` server-side, which
+     * boosts ARCHITECTURE / GIT / API spines and dampens DOCUMENT / VISION.
+     * Other valid scopes depend on the host's `type-weights.ts` table.
+     */
+    scope?: string;
+    /**
+     * [SDK 1.2] Optional whitelist of spineTypes to restrict results to.
+     * Server-side SQL `IN` clause. Example: `['ARCHITECTURE', 'GIT']` to
+     * surface design docs + commit history only.
+     */
+    spineTypeFilter?: string[];
 }
 interface Chronicle {
     id: string;
@@ -117,10 +179,33 @@ interface Chronicle {
     timestamp: string;
     source_app_id: string;
 }
+/**
+ * [SDK 1.2 — Semantic Bridge] Debug breadcrumb returned by the server when
+ * the client opted into `semantic: true`. Lets agents distinguish "I asked
+ * for semantic and got it" from "I asked for semantic and it silently fell
+ * back to recent" (and why). Only populated on opt-in.
+ */
+interface QuerySemanticDebug {
+    /** Did the client request semantic ranking? Always true when this field is present. */
+    wanted: boolean;
+    /** Did the semantic branch actually execute? (false ⇒ fell back to recent, see `error`) */
+    used: boolean;
+    /** Dimension of the embedding vector used (768 for Vertex/e5-base, 512 for nomic local). */
+    vectorDim?: number;
+    /** Total chronicle count in the target vault at query time. */
+    vaultSize?: number;
+    /** Error message if `used` is false. Examples: provider not registered, vector dim mismatch. */
+    error?: string;
+}
 interface QueryResult {
     success: boolean;
     chronicles: Chronicle[];
     error?: string;
+    /**
+     * [SDK 1.2] Present only when the client sent `semantic: true`. See
+     * {@link QuerySemanticDebug}. Absent on fast-path / non-opt-in queries.
+     */
+    _semantic?: QuerySemanticDebug;
 }
 interface ShareRequest {
     /** App source dont on veut lire les vecteurs */
@@ -140,6 +225,135 @@ interface RegisterResult {
     expiresAt: number;
     appId: string;
 }
+/**
+ * Describes a vault (core or custom) returned by `sdk.vaults.list`.
+ * Use `id` as the `vault` parameter in `ingest()` and `query()` calls.
+ */
+interface VaultInfo {
+    /** Unique vault identifier (uppercase, e.g. `'DEV'`, `'MY_NOTES'`). */
+    id: string;
+    /** Human-readable display name. */
+    displayName: string;
+    /** Whether this is a built-in core vault (`true`) or user-created (`false`). */
+    fixed: boolean;
+    /** Accent color (hex) for UI rendering. */
+    color: string;
+    /** Chronicle count at query time. */
+    chronicleCount: number;
+    /** SQLite file size in KB. */
+    sizeKb: number;
+}
+interface VaultListResult {
+    success: boolean;
+    /** Core vaults (DEV, SOCIAL, PERSONAL, FINANCE, RESEARCH). */
+    coreVaults: VaultInfo[];
+    /** User-created custom vaults. */
+    customVaults: VaultInfo[];
+    error?: string;
+}
+/**
+ * Options for a causal/semantic correlation query.
+ * Finds chronicles that are causally or semantically linked to a source chronicle.
+ */
+interface CorrelateOptions {
+    /** ID of the source chronicle to find correlations for. */
+    sourceId: string;
+    /** Maximum number of correlations to return (default: 10). */
+    limit?: number;
+    /** Vault to search in (defaults to the app's primary vault). */
+    vault?: MnemoVault;
+    /** Minimum correlation strength 0-1 (default: 0.5). */
+    threshold?: number;
+}
+interface CorrelationEntry {
+    chronicle: Chronicle;
+    /** Correlation strength between 0 and 1. */
+    strength: number;
+    /** Nature of the link between the two chronicles. */
+    type: 'causal' | 'temporal' | 'semantic';
+}
+interface CorrelateResult {
+    success: boolean;
+    correlations: CorrelationEntry[];
+    error?: string;
+}
+/**
+ * Result of a `sdk.forget` call.
+ * Deletes a chronicle by ID from the vault. Requires `vault:write:*` scope.
+ */
+interface ForgetResult {
+    success: boolean;
+    /** ID of the deleted chronicle. */
+    deletedId: string;
+    error?: string;
+}
+/**
+ * Request to allocate a new dynamic spine in the OS registry.
+ * Dynamic spines allow Layer 2 apps to define their own semantic categories
+ * that appear in the Mnemosyne OS neural graph alongside core spine types.
+ *
+ * Requires scope `vault:write:CUSTOM` and the Protocole du Guichet to be active.
+ */
+interface DynamicSpineRequest {
+    /** Unique ID for this spine (snake_case, e.g. `'my_app_events'`). */
+    id: string;
+    /** Display name shown in the OS neural graph. */
+    name: string;
+    /** Base spine type to inherit semantic weight from. */
+    type: SpineType | string;
+    /** Emoji or icon key for UI rendering. */
+    icon: string;
+    /** Short description of what this spine captures. */
+    description?: string;
+}
+interface DynamicSpineResult {
+    success: boolean;
+    /** Full spine ID as registered (may be namespaced, e.g. `'my-app/my_events'`). */
+    spineId?: string;
+    error?: string;
+}
+interface DynamicSpineInfo {
+    id: string;
+    name: string;
+    type: string;
+    icon: string;
+    /** App ID that owns this spine. */
+    ownerAppId: string;
+    /** ISO timestamp of allocation. */
+    allocatedAt: string;
+}
+/**
+ * A Resonance record returned by `sdk.resonances.list`.
+ * Resonances are cognitive projects tracked in the DEV vault.
+ */
+interface ResonanceRecord {
+    /** Unique resonance identifier (e.g. `'agent-cockpit'`). */
+    id: string;
+    /** Display name of the resonance. */
+    name: string;
+    /** Current lifecycle status. */
+    status: 'active' | 'paused' | 'done';
+    spineType: 'RESONANCE';
+    /** Number of chronicles tagged with this resonance. */
+    spineCount: number;
+    /** Number of agents currently working on this resonance. */
+    agentCount: number;
+    /** Milliseconds since last activity. */
+    lastActivity: number;
+    /** Last known position string (set via `updatePosition`). */
+    lastPosition?: string;
+}
+/**
+ * Result of `sdk.resonance.updatePosition`.
+ */
+interface PositionUpdateResult {
+    /** Whether the position was persisted. */
+    ok: boolean;
+    resonanceId: string;
+    phase: string;
+    /** Unix timestamp (ms) of the update. */
+    ts: number;
+}
 /**
  * Un commit git retourné par MNEMOSYNE_METHODS.GIT_LOG.
  * Le path du repo est hardcodé côté serveur (Zero-Trust).
@@ -154,6 +368,21 @@ interface GitCommit {
     ts: number;
     repo: string;
 }
+/** Options for MnemoClient.gitLog(). */
+interface GitLogOptions {
+    /** Number of commits to return (default: 20, server cap: 50). */
+    limit?: number;
+    /** Time range filter (e.g. "7 days ago", "2024-01-01"). */
+    since?: string;
+    /** Filter commits by message pattern (e.g. "[RESONANCE:agent-cockpit]"). */
+    filter?: string;
+}
+/** Result of MnemoClient.gitLog(). */
+interface GitLogResult {
+    success: boolean;
+    commits: GitCommit[];
+    error?: string;
+}
 /**
  * Un agent SDK retourné par MNEMOSYNE_METHODS.LIST_AGENTS.
  */
@@ -209,7 +438,94 @@ interface GraphQueryResult {
     centerNodeId?: string;
     error?: string;
 }
-type MnemoEventType = 'connected' | 'disconnected' | 'error' | 'tamper-alert' | 'share-request' | 'nft-revoked';
+type MnemoEventType = 'connected' | 'disconnected' | 'error' | 'tamper-alert' | 'share-request'
+/** Fired when a connected NFT licence is transferred mid-session. */
+ | 'nft-revoked'
+/** Fired by the OS when another app ingests a new chronicle. */
+ | 'chronicle:new'
+/** Fired when a Layer 2 dynamic spine is allocated or released. */
+ | 'spine:change'
+/**
+ * [PHASE-58] Fired after each Semantic Reflect scan persists new bridges.
+ * payload: { sessionId, newCount, knownCount, totalFound }
+ */
+ | 'bridge:new';
+/**
+ * A semantic bridge between two chronicles in different vaults.
+ * Returned by getBridgeHistory().
+ * [PHASE-58][PLATFORM][READ-ONLY]
+ */
+interface BridgeRecord {
+    id: number;
+    scanned_at: string;
+    from_id: number;
+    from_vault: string;
+    from_spine: string;
+    from_label: string;
+    to_id: number;
+    to_vault: string;
+    to_spine: string;
+    to_label: string;
+    /** Cosine similarity score (0-1). High values = strong cognitive link. */
+    cosine: number;
+    /** UUID of the scan session that discovered this bridge. */
+    session_id: string | null;
+    /** 1 if this bridge was never seen before this scan, 0 if already known. */
+    is_new: 0 | 1;
+    /** JSON array of tags (reserved for future use). */
+    tags: string;
+}
+/**
+ * A bridge scan session — groups all bridges found in one Semantic Reflect run.
+ */
+interface BridgeScanSession {
+    /** UUID — unique session identifier. */
+    id: string;
+    scanned_at: string;
+    threshold: number;
+    total_found: number;
+    new_count: number;
+    llm_synthesis: string | null;
+    duration_ms: number | null;
+}
+/** Options for getBridgeHistory(). */
+interface BridgeHistoryOptions {
+    /** Maximum bridges to return (default: 500). */
+    limit?: number;
+    /** ISO timestamp — only return bridges after this date. */
+    since?: string;
+    /** Minimum cosine similarity (0-1, default: 0.0). */
+    minCosine?: number;
+    /** Filter by source vault (default: 'ALL'). */
+    vaultFilter?: 'DEV' | 'SOCIAL' | 'PERSONAL' | 'ALL';
+    /** Only return bridges that were new when first discovered. */
+    onlyNew?: boolean;
+}
+/** Result of getBridgeHistory(). */
+interface BridgeHistoryResult {
+    success: boolean;
+    bridges: BridgeRecord[];
+    error?: string;
+}
+/**
+ * Result of computeResonance() — resonance score for a text before publication.
+ * [PLATFORM] Use this to gate social posts on cognitive relevance.
+ */
+interface ResonanceScore {
+    success: boolean;
+    /** Aggregated cosine score (0-1). */
+    score: number;
+    /** Qualitative band: LOW (<0.60), MEDIUM (0.60-0.80), HIGH_RESONANCE (>0.80). */
+    level: 'LOW' | 'MEDIUM' | 'HIGH_RESONANCE';
+    /** Top K matching bridges. */
+    topMatches: Array<{
+        bridgeId: number;
+        fromLabel: string;
+        toLabel: string;
+        cosine: number;
+        vault: string;
+    }>;
+}
 interface MnemoEvent<T = unknown> {
     type: MnemoEventType;
     data: T;
@@ -351,6 +667,13 @@ declare class MnemoClient {
      * [PHASE-50] Lit un fichier .md depuis le repo OS (docs/, packages/).
      */
     readFile(path: string): Promise<string>;
+    /**
+     * 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.
+     */
+    gitLog(options?: GitLogOptions): Promise<GitLogResult>;
 }
 
 /**
@@ -416,25 +739,27 @@ declare class MnemoClientBrowser {
      * 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 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}.
      */
-    query(text: string, vault?: string, limit?: number): Promise<Chronicle[]>;
+    query(text: string, vault?: string, limit?: number, options?: Pick<QueryOptions, 'semantic' | 'scope' | 'spineTypeFilter'>): Promise<Chronicle[]>;
     /**
-     * Retourne les Resonances actives (projets cognitifs) depuis le vault DEV.
-     * Requiert le scope `vault:read:DEV`.
+     * Returns the active Resonances (cognitive projects) from the DEV vault.
+     * Requires scope `vault:read:DEV`.
      */
-    resonancesList(): Promise<Record<string, unknown>[]>;
+    resonancesList(): Promise<ResonanceRecord[]>;
     /**
-     * Persiste la position courante d'une Resonance dans le vault DEV.
-     * Requiert le scope `vault:write:DEV`.
+     * Persists the current position of a Resonance in the DEV vault.
+     * Requires scope `vault:write:DEV`.
      *
-     * @param resonanceId - ID de la Resonance
-     * @param position    - Description de la position courante (ex: "Phase 51.2 — auto-poll")
-     * @param phase       - Phase courante (ex: "Phase 51")
+     * @param resonanceId - Resonance identifier
+     * @param position    - Current position description (e.g. 'Phase 51.2 — auto-poll')
+     * @param phase       - Current phase (e.g. 'Phase 51')
      */
-    updatePosition(resonanceId: string, position: string, phase: string): Promise<boolean>;
+    updatePosition(resonanceId: string, position: string, phase: string): Promise<PositionUpdateResult>;
     /**
      * Retourne les commits récents du monorepo Mnemosyne OS.
      * Requiert le scope `monorepo:read` et l'intent `GIT_LOG`.
@@ -453,10 +778,103 @@ declare class MnemoClientBrowser {
      */
     readFile(path: string): Promise<string>;
     /**
-     * Liste les apps Layer 2 actuellement connectées au SDK WebSocket Server.
-     * Requiert le scope `agents:read` et l'intent `LIST_AGENTS`.
+     * Lists Layer 2 apps currently connected to the SDK WebSocket Server.
+     * Requires scope `agents:read` and intent `LIST_AGENTS`.
      */
     agentsList(): Promise<AgentInfo[]>;
+    /**
+     * 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`.
+     */
+    vaultsList(): Promise<VaultListResult>;
+    /**
+     * 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? }`
+     */
+    correlate(options: CorrelateOptions): Promise<CorrelateResult>;
+    /**
+     * 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').
+     */
+    forget(chronicleId: string, vault?: string): Promise<ForgetResult>;
+    /**
+     * 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).
+     */
+    graphQuery(text: string, threshold?: number): Promise<GraphQueryResult>;
+    /**
+     * 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: '📊'
+     * });
+     * ```
+     */
+    spineRegister(spine: DynamicSpineRequest): Promise<DynamicSpineResult>;
+    /**
+     * Releases a dynamic spine previously allocated by this app.
+     * Requires scope `vault:write:CUSTOM`.
+     */
+    spineRelease(spineId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Lists all currently allocated dynamic spines across all apps.
+     */
+    spineList(): Promise<DynamicSpineInfo[]>;
+    /**
+     * 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`);
+     * ```
+     */
+    getBridgeHistory(options?: BridgeHistoryOptions): Promise<BridgeHistoryResult>;
+    /**
+     * 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!');
+     * }
+     * ```
+     */
+    computeResonance(text: string, topK?: number): Promise<ResonanceScore>;
     /**
      * 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`).
@@ -503,7 +921,7 @@ declare class MnemoClientBrowser {
  * [SDK][ZERO-TRUST][AUDIT-TRAIL][MN-004]
  */
 
-declare const VALID_SCOPES: readonly ["vault:read:DEV", "vault:write:DEV", "vault:read:SOCIAL", "vault:write:SOCIAL", "vault:read:PERSONAL", "vault:write:PERSONAL", "vault:read:FINANCE", "vault:write:FINANCE", "vault:read:COOK", "vault:write:COOK", "share:request", "share:grant", "nft:validate", "neural:graph:read", "llm:query"];
+declare const VALID_SCOPES: readonly ["vault:read:DEV", "vault:write:DEV", "vault:read:SOCIAL", "vault:write:SOCIAL", "vault:read:PERSONAL", "vault:write:PERSONAL", "vault:read:FINANCE", "vault:write:FINANCE", "vault:read:RESEARCH", "vault:write:RESEARCH", "vault:read:CUSTOM", "vault:write:CUSTOM", "share:request", "share:grant", "monorepo:read", "agents:read", "nft:validate", "neural:graph:read", "llm:query", "bridge:read"];
 /**
  * Scopes qui requièrent TOUJOURS un GRANT utilisateur côté OS.
  * Indépendant de tout flag déclaré par l'app.
@@ -516,9 +934,15 @@ declare const AppManifestSchema: z.ZodObject<{
     version: z.ZodString;
     author: z.ZodOptional<z.ZodString>;
     mnemosyne_sdk: z.ZodString;
-    scopes: z.ZodArray<z.ZodEnum<["vault:read:DEV", "vault:write:DEV", "vault:read:SOCIAL", "vault:write:SOCIAL", "vault:read:PERSONAL", "vault:write:PERSONAL", "vault:read:FINANCE", "vault:write:FINANCE", "vault:read:COOK", "vault:write:COOK", "share:request", "share:grant", "nft:validate", "neural:graph:read", "llm:query"]>, "many">;
-    vaults: z.ZodArray<z.ZodEnum<["DEV", "SOCIAL", "PERSONAL", "FINANCE", "COOK"]>, "many">;
-    intents: z.ZodArray<z.ZodEnum<["INGEST", "QUERY", "CORRELATE", "FORGET"]>, "many">;
+    scopes: z.ZodArray<z.ZodEnum<["vault:read:DEV", "vault:write:DEV", "vault:read:SOCIAL", "vault:write:SOCIAL", "vault:read:PERSONAL", "vault:write:PERSONAL", "vault:read:FINANCE", "vault:write:FINANCE", "vault:read:RESEARCH", "vault:write:RESEARCH", "vault:read:CUSTOM", "vault:write:CUSTOM", "share:request", "share:grant", "monorepo:read", "agents:read", "nft:validate", "neural:graph:read", "llm:query", "bridge:read"]>, "many">;
+    /**
+     * 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.ZodArray<z.ZodUnion<[z.ZodEnum<["DEV", "SOCIAL", "PERSONAL", "FINANCE", "RESEARCH"]>, z.ZodString]>, "many">;
+    intents: z.ZodArray<z.ZodEnum<["INGEST", "QUERY", "CORRELATE", "FORGET", "GIT_LOG", "LIST_AGENTS", "LIST_VAULTS", "BRIDGE_READ"]>, "many">;
     max_chronicle_size_kb: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     /**
      * @deprecated Remplacé par requiresOsGrant() — ce flag n'a aucun effet sur la sécurité.
@@ -531,9 +955,9 @@ declare const AppManifestSchema: z.ZodObject<{
     name: string;
     version: string;
     mnemosyne_sdk: string;
-    scopes: ("vault:read:DEV" | "vault:write:DEV" | "vault:read:SOCIAL" | "vault:write:SOCIAL" | "vault:read:PERSONAL" | "vault:write:PERSONAL" | "vault:read:FINANCE" | "vault:write:FINANCE" | "vault:read:COOK" | "vault:write:COOK" | "share:request" | "share:grant" | "nft:validate" | "neural:graph:read" | "llm:query")[];
-    vaults: ("DEV" | "SOCIAL" | "PERSONAL" | "FINANCE" | "COOK")[];
-    intents: ("INGEST" | "QUERY" | "CORRELATE" | "FORGET")[];
+    scopes: ("vault:read:DEV" | "vault:write:DEV" | "vault:read:SOCIAL" | "vault:write:SOCIAL" | "vault:read:PERSONAL" | "vault:write:PERSONAL" | "vault:read:FINANCE" | "vault:write:FINANCE" | "vault:read:RESEARCH" | "vault:write:RESEARCH" | "vault:read:CUSTOM" | "vault:write:CUSTOM" | "share:request" | "share:grant" | "monorepo:read" | "agents:read" | "nft:validate" | "neural:graph:read" | "llm:query" | "bridge:read")[];
+    vaults: string[];
+    intents: ("INGEST" | "QUERY" | "CORRELATE" | "FORGET" | "GIT_LOG" | "LIST_AGENTS" | "LIST_VAULTS" | "BRIDGE_READ")[];
     max_chronicle_size_kb: number;
     requires_consent: boolean;
     author?: string | undefined;
@@ -543,9 +967,9 @@ declare const AppManifestSchema: z.ZodObject<{
     name: string;
     version: string;
     mnemosyne_sdk: string;
-    scopes: ("vault:read:DEV" | "vault:write:DEV" | "vault:read:SOCIAL" | "vault:write:SOCIAL" | "vault:read:PERSONAL" | "vault:write:PERSONAL" | "vault:read:FINANCE" | "vault:write:FINANCE" | "vault:read:COOK" | "vault:write:COOK" | "share:request" | "share:grant" | "nft:validate" | "neural:graph:read" | "llm:query")[];
-    vaults: ("DEV" | "SOCIAL" | "PERSONAL" | "FINANCE" | "COOK")[];
-    intents: ("INGEST" | "QUERY" | "CORRELATE" | "FORGET")[];
+    scopes: ("vault:read:DEV" | "vault:write:DEV" | "vault:read:SOCIAL" | "vault:write:SOCIAL" | "vault:read:PERSONAL" | "vault:write:PERSONAL" | "vault:read:FINANCE" | "vault:write:FINANCE" | "vault:read:RESEARCH" | "vault:write:RESEARCH" | "vault:read:CUSTOM" | "vault:write:CUSTOM" | "share:request" | "share:grant" | "monorepo:read" | "agents:read" | "nft:validate" | "neural:graph:read" | "llm:query" | "bridge:read")[];
+    vaults: string[];
+    intents: ("INGEST" | "QUERY" | "CORRELATE" | "FORGET" | "GIT_LOG" | "LIST_AGENTS" | "LIST_VAULTS" | "BRIDGE_READ")[];
     author?: string | undefined;
     max_chronicle_size_kb?: number | undefined;
     requires_consent?: boolean | undefined;
@@ -562,8 +986,12 @@ declare function loadManifest(pathOrManifest: string | AppManifest): AppManifest
  */
 declare function parseManifest(raw: unknown): AppManifest;
 /**
- * Vérifie qu'un scope est déclaré dans le manifest.
- * Utilisé par MnemoClient avant chaque opération.
+ * Validates that a scope is declared in the manifest.
+ * Used by MnemoClient before each vault operation.
+ *
+ * For custom vault operations, the scope `vault:read:CUSTOM` or
+ * `vault:write:CUSTOM` is accepted as a wildcard that grants access
+ * to any custom vault listed in `manifest.vaults`.
  */
 declare function assertScope(manifest: AppManifest, scope: (typeof VALID_SCOPES)[number]): void;
 /**
@@ -660,10 +1088,34 @@ declare const MNEMOSYNE_METHODS: {
      */
     readonly NFT_VALIDATE: "sdk.nft.validate";
     /**
-     * Requête le NeuralGraph — retourne les nœuds et arêtes proches du texte.
-     * Requiert le scope `neural:graph:read` dans le manifest.
+     * Queries the NeuralGraph — returns nodes and edges near the given text.
+     * Requires scope `neural:graph:read`.
      */
     readonly GRAPH_QUERY: "sdk.graph.query";
+    /**
+     * 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.
+     */
+    readonly LIST_VAULTS: "sdk.vaults.list";
+    /**
+     * 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.
+     */
+    readonly 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`.
+     */
+    readonly RELEASE_SPINE: "sdk.spine.release";
+    /**
+     * Lists all currently allocated dynamic spines across all registered apps.
+     * Returns an array of `DynamicSpineInfo` objects.
+     */
+    readonly LIST_SPINES: "sdk.spine.list";
 };
 type MnemoMethod = typeof MNEMOSYNE_METHODS[keyof typeof MNEMOSYNE_METHODS];
 /** Port par défaut du SDK WebSocket Server */
@@ -693,4 +1145,4 @@ declare const MNEMOSYNE_CHAINS: {
 };
 type MnemoChain = keyof typeof MNEMOSYNE_CHAINS;
 
-export { type AgentInfo, type AppManifest, AppManifestSchema, type Chronicle, GRANT_REQUIRED_SCOPE_PREFIXES, type GitCommit, type GraphEdge, type GraphNode, type GraphQueryResult, type IngestPayload, type IngestResult, type JwtPayload, type JwtVerifyResult, MNEMOSYNE_CHAINS, MNEMOSYNE_METHODS, MNEMOSYNE_NFT_CACHE_TTL_MS, MNEMOSYNE_TOKEN_TTL_S, MNEMOSYNE_WS_HOST, MNEMOSYNE_WS_PORT, type MnemoChain, MnemoClient, MnemoClientBrowser, type MnemoClientOptions, type MnemoEvent, type MnemoEventType, type MnemoIntent, type MnemoMethod, type MnemoScope, type MnemoVault, type NFTLicenseParams, type NFTValidation, type QueryOptions, type QueryResult, type RegisterResult, type ShareRequest, type ShareResult, type SpineType, assertScope, assertVault, generateAppToken, generateSecret, loadManifest, parseManifest, requiresOsGrant, verifyToken };
+export { type AgentInfo, type AppManifest, AppManifestSchema, type BridgeHistoryOptions, type BridgeHistoryResult, type BridgeRecord, type BridgeScanSession, type Chronicle, type CorrelateOptions, type CorrelateResult, type CorrelationEntry, type DynamicSpineInfo, type DynamicSpineRequest, type DynamicSpineResult, type ForgetResult, GRANT_REQUIRED_SCOPE_PREFIXES, type GitCommit, type GitLogOptions, type GitLogResult, type GraphEdge, type GraphNode, type GraphQueryResult, type IngestPayload, type IngestResult, type JwtPayload, type JwtVerifyResult, MNEMOSYNE_CHAINS, MNEMOSYNE_METHODS, MNEMOSYNE_NFT_CACHE_TTL_MS, MNEMOSYNE_TOKEN_TTL_S, MNEMOSYNE_WS_HOST, MNEMOSYNE_WS_PORT, type MnemoChain, MnemoClient, MnemoClientBrowser, type MnemoClientOptions, type MnemoEvent, type MnemoEventType, type MnemoIntent, type MnemoMethod, type MnemoScope, type MnemoVault, type NFTLicenseParams, type NFTValidation, type PositionUpdateResult, type QueryOptions, type QueryResult, type QuerySemanticDebug, type RegisterResult, type ResonanceRecord, type ResonanceScore, type ShareRequest, type ShareResult, type SpineType, type VaultInfo, type VaultListResult, assertScope, assertVault, generateAppToken, generateSecret, loadManifest, parseManifest, requiresOsGrant, verifyToken };