@mnemosyne_os/sdk 1.0.0 → 1.2.0

package/dist/index.d.cts

@@ -1,27 +1,73 @@
 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'
-/** Validation de licence NFT on-chain pour MnemoStore */
+/**
+ * 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'
+/** List active connected SDK agents. */
+ | 'agents:read'
+/** 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 */
-type MnemoIntent = 'INGEST' | 'QUERY' | 'CORRELATE' | 'FORGET';
-/** Vault cible */
-type MnemoVault = 'DEV' | 'SOCIAL' | 'PERSONAL' | 'FINANCE' | 'COOK';
-/** Types de spine */
-type SpineType = 'GIT' | 'ARCHITECTURE' | 'DECISION' | 'DEBUG' | 'FEATURE' | 'REDDIT_POST' | 'LINKEDIN_POST' | 'SOCIAL_NODE' | 'DOCUMENT' | 'NOTE' | 'CUSTOM';
+/** 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 */
+ | 'RESONANCE'
+/** Persistance de session / contexte de reprise */
+ | 'SESSION'
+/** Mise à jour de position (phase, état courant) */
+ | '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é) */
@@ -95,19 +141,71 @@ 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;
-    content: string;
+    /** Contenu textuel du chronicle. Peut être absent si seul le vecteur est stocké. */
+    content?: string;
     spineType: SpineType;
     score: number;
     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 */
@@ -127,6 +225,175 @@ 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).
+ */
+interface GitCommit {
+    hash: string;
+    fullHash?: string;
+    author: string;
+    message: string;
+    /** Type conventional commit (feat/fix/chore/…) */
+    type: string;
+    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.
+ */
+interface AgentInfo {
+    id: string;
+    name: string;
+    provider: string;
+    status: 'active' | 'idle' | 'offline';
+    resonanceId?: string;
+    sessionMs?: number;
+}
 /**
  * Paramètres pour valider une licence NFT.
  * La validation se fait on-chain via le runtime Mnemosyne OS (pas directement dans le SDK).
@@ -171,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;
@@ -187,7 +541,14 @@ interface MnemoEvent<T = unknown> {
  * Format : base64url(header).base64url(payload).base64url(signature)
  * Algorithme : HMAC-SHA256 (symétrique, secret partagé OS ↔ app)
  *
- * [SDK][SECURITY][AUTH]
+ * ## Compat Browser (MN-005)
+ * `Buffer.toString('base64url')` n'est pas supporté par le polyfill npm `buffer`.
+ * Les helpers b64url() / parseB64url() utilisent une impl universelle :
+ *   - Node.js  : Buffer natif (supporte base64url)
+ *   - Browser  : btoa/atob + remplacement des caractères non-URL
+ * Cela permet d'importer les CONSTANTES du SDK dans un renderer Electron sans crash.
+ *
+ * [SDK][SECURITY][AUTH][MN-005]
  */
 interface JwtPayload {
     sub: string;
@@ -293,12 +654,256 @@ declare class MnemoClient {
     get isConnected(): boolean;
     get appId(): string;
     get appManifest(): AppManifest;
-    /** 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(): {
         sub: string;
         exp: number;
         scopes: string[];
     } | null;
+    /**
+     * [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>;
+}
+
+/**
+ * @mnemosyne_os/sdk — MnemoClientBrowser
+ *
+ * Client WebSocket 100% browser-native pour les apps Layer 2 qui tournent
+ * dans un renderer Electron ou un navigateur web.
+ * N'utilise PAS le package `ws` (Node-only) — uniquement l'API WebSocket native.
+ *
+ * Usage dans une app React/Vite :
+ * ```typescript
+ * import { MnemoClientBrowser } from '@mnemosyne_os/sdk';
+ *
+ * const client = await MnemoClientBrowser.connect();
+ * await client.register({ id: 'my-app', name: 'My App', version: '1.0.0',
+ *   mnemosyne_sdk: '^1.1.0', scopes: ['vault:read:DEV'], vaults: ['DEV'], intents: ['QUERY'] });
+ *
+ * const chronicles = await client.query('my search', 'DEV', 10);
+ * ```
+ *
+ * [SDK][LAYER-2][BROWSER][ZERO-TRUST]
+ */
+
+/**
+ * Client SDK browser-native. Communique avec le SDK WebSocket Server de
+ * Mnemosyne OS sur ws://127.0.0.1:7799 via l'API WebSocket standard.
+ *
+ * Compatible : Chrome, Firefox, Electron renderer, Safari, Vite, Next.js.
+ * Non compatible : Node.js (utiliser MnemoClient à la place).
+ */
+declare class MnemoClientBrowser {
+    private readonly ws;
+    private token;
+    private readonly pending;
+    private _onPush?;
+    private _onDisconnect?;
+    private readonly timeoutMs;
+    private constructor();
+    /**
+     * 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?: string, port?: number, timeoutMs?: number): Promise<MnemoClientBrowser>;
+    private _handleMsg;
+    private call;
+    /**
+     * 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
+     */
+    register(manifest: AppManifest): Promise<RegisterResult>;
+    /**
+     * 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`.
+     */
+    ingest(content: string, spineType: string, vault?: string, metadata?: Record<string, unknown>): Promise<IngestResult>;
+    /**
+     * 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}.
+     */
+    query(text: string, vault?: string, limit?: number, options?: Pick<QueryOptions, 'semantic' | 'scope' | 'spineTypeFilter'>): Promise<Chronicle[]>;
+    /**
+     * Returns the active Resonances (cognitive projects) from the DEV vault.
+     * Requires scope `vault:read:DEV`.
+     */
+    resonancesList(): Promise<ResonanceRecord[]>;
+    /**
+     * 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')
+     */
+    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`.
+     * [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')
+     */
+    gitLog(limit?: number, since?: string): Promise<GitCommit[]>;
+    /**
+     * 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')
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * 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`).
+     *
+     * @example
+     * ```typescript
+     * client.onPush((event) => {
+     *   if (event.type === 'chronicle:new') {
+     *     console.log('New chronicle from:', event.sourceApp);
+     *   }
+     * });
+     * ```
+     */
+    onPush(fn: (event: Record<string, unknown>) => void): void;
+    /**
+     * Enregistre un callback appelé quand la connexion WS est fermée par l'OS.
+     */
+    onDisconnect(fn: () => void): void;
+    /**
+     * Ferme la connexion WebSocket proprement.
+     */
+    close(): void;
+    get isConnected(): boolean;
+    /** Token JWT actuel (null avant register()) */
+    get currentToken(): string | null;
+    /**
+     * AppId extrait du JWT actuel, ou null si non enregistré.
+     */
+    get appId(): string | null;
 }
 
 /**
@@ -307,30 +912,52 @@ declare class MnemoClient {
  * Valide le fichier app.manifest.json avant toute connexion.
  * Utilise Zod pour un parsing strict — aucun champ inconnu passé au serveur.
  *
- * [SDK][ZERO-TRUST][AUDIT-TRAIL]
+ * ## Règle Zero-Trust (MN-004)
+ * Le GRANT utilisateur est TOUJOURS requis si l'app déclare un scope vault:*.
+ * Ce n'est PAS un flag que l'app contrôle — c'est l'OS qui décide en lisant les scopes.
+ * Un manifest avec `requires_grant: false` mais `scopes: ['vault:read:DEV']` DOIT
+ * quand même passer par le popup de consentement. L'OS appelle `requiresOsGrant(manifest)`.
+ *
+ * [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"];
+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.
+ * [MN-004]
+ */
+declare const GRANT_REQUIRED_SCOPE_PREFIXES: readonly ["vault:read:", "vault:write:", "share:request", "share:grant", "llm:query"];
 declare const AppManifestSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     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"]>, "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é.
+     * L'OS décide toujours en fonction des scopes déclarés (MN-004).
+     */
     requires_consent: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     description: z.ZodOptional<z.ZodString>;
-}, "strict", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     id: string;
     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")[];
-    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;
@@ -340,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")[];
-    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;
@@ -359,14 +986,39 @@ 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;
 /**
  * Vérifie qu'un vault est accessible selon le manifest.
  */
 declare function assertVault(manifest: AppManifest, vault: string): void;
+/**
+ * [MN-004] Détermine si l'OS DOIT afficher un popup de consentement utilisateur
+ * AVANT d'autoriser cette app à s'exécuter.
+ *
+ * La décision est basée UNIQUEMENT sur les scopes déclarés dans le manifest.
+ * Elle est imperméable à tout flag (`requires_grant`, `requires_consent`) que
+ * l'app pourrait contrôler elle-même.
+ *
+ * Règle : tout scope avec préfixe `vault:*`, `share:*` ou `llm:query` → GRANT requis.
+ *
+ * @example
+ * ```typescript
+ * import { requiresOsGrant } from '@mnemosyne_os/sdk';
+ * // Dans LAUNCH_LAYER2_APP (main process) :
+ * if (requiresOsGrant(appManifest)) {
+ *   const granted = await showPermissionPrompt(appManifest);
+ *   if (!granted) return { success: false, error: 'GRANT_DENIED' };
+ * }
+ * ```
+ */
+declare function requiresOsGrant(manifest: Pick<AppManifest, 'scopes'>): boolean;
 
 /**
  * @mnemosyne_os/sdk — Public Constants
@@ -398,6 +1050,35 @@ declare const MNEMOSYNE_METHODS: {
     readonly CORRELATE: "sdk.correlate";
     /** Supprime un chronicle par ID (scope vault:write requis) */
     readonly FORGET: "sdk.forget";
+    /**
+     * Liste les Resonances actives (projets cognitifs) depuis le vault DEV.
+     * Requiert le scope `vault:read:DEV`.
+     */
+    readonly 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`.
+     */
+    readonly UPDATE_POSITION: "sdk.resonance.updatePosition";
+    /**
+     * 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.
+     */
+    readonly 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.
+     */
+    readonly READ_FILE: "sdk.readFile";
+    /**
+     * Liste les agents actifs connectés au SDK WebSocket Server.
+     * Requiert le scope `agents:read` dans le manifest.
+     */
+    readonly LIST_AGENTS: "sdk.agents.list";
     /** Demande d'accès aux chronicles d'une autre app (popup consentement) */
     readonly SHARE: "sdk.share";
     /**
@@ -407,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 */
@@ -440,4 +1145,4 @@ declare const MNEMOSYNE_CHAINS: {
 };
 type MnemoChain = keyof typeof MNEMOSYNE_CHAINS;
 
-export { type AppManifest, AppManifestSchema, type Chronicle, 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, 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, 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 };