@soulcraft/sdk 1.0.0

package/dist/server/instance-pool.d.ts

@@ -0,0 +1,299 @@
+/**
+ * @module server/instance-pool
+ * @description Brainy instance pool for server-mode SDK.
+ *
+ * Manages a pool of live Brainy instances using one of three strategies:
+ *
+ * - **`per-user`** (Workshop): one instance per `emailHash:workspaceId`. Storage path:
+ *   `{dataPath}/{emailHash}/{workspaceId}/`. Suited to many users each with their own
+ *   graph.
+ * - **`per-tenant`** (Venue): one instance per tenant slug. Storage path:
+ *   `{dataPath}/{tenantSlug}/`. The LRU max prevents memory exhaustion on high-traffic
+ *   installations.
+ * - **`per-scope`**: caller-supplied key function `scopeKey(userId, workspaceId)`. Covers
+ *   Academy and any bespoke use case.
+ *
+ * ## LRU eviction
+ *
+ * The pool is backed by `lru-cache`. When an entry is evicted (because the cache is
+ * full), the `dispose` callback fires synchronously. If `flushOnEvict` is `true`, a
+ * non-blocking `brain.flush()` call is queued — the eviction itself is not delayed.
+ * Call `flushAll()` or `shutdown()` before process exit to guarantee all writes are
+ * persisted.
+ *
+ * ## Concurrency
+ *
+ * Concurrent requests for the same scope key are deduplicated via a pending-init map.
+ * Only one Brainy instance is ever created per key, regardless of how many requests
+ * arrive simultaneously during cold start.
+ *
+ * @example
+ * ```typescript
+ * import { BrainyInstancePool } from '@soulcraft/sdk/server'
+ *
+ * const pool = new BrainyInstancePool({
+ *   storage: 'mmap-filesystem',
+ *   dataPath: '/mnt/brainy-data',
+ *   strategy: 'per-user',
+ *   maxInstances: 200,
+ *   flushOnEvict: true,
+ * })
+ *
+ * // In a request handler:
+ * const brain = await pool.forUser(session.user.emailHash, workspaceId)
+ * const results = await brain.find({ query: 'inventory items' })
+ * ```
+ */
+import { Brainy } from '@soulcraft/brainy';
+import type { InstanceStrategy } from '../types.js';
+/**
+ * Configuration for {@link BrainyInstancePool}.
+ */
+export interface InstancePoolConfig {
+    /**
+     * Brainy storage backend.
+     *
+     * - `'filesystem'` — local dev, plain filesystem storage.
+     * - `'mmap-filesystem'` — production on GCE; Cortex upgrades filesystem to mmap
+     *   automatically via the `@soulcraft/cortex` plugin.
+     */
+    storage: 'filesystem' | 'mmap-filesystem';
+    /**
+     * Root directory for Brainy data. Instances are stored in sub-directories
+     * determined by the pooling strategy.
+     */
+    dataPath: string;
+    /** Instance pooling strategy. */
+    strategy: InstanceStrategy;
+    /**
+     * Custom scope-key function for `'per-scope'` strategy.
+     *
+     * Called with `(userId, workspaceId)` and must return a unique, stable string
+     * key that identifies the Brainy instance for that request.
+     *
+     * @param userId - The authenticated user's identifier (usually email hash).
+     * @param workspaceId - The workspace or resource identifier.
+     * @returns A unique string key for this scope.
+     */
+    scopeKey?: (userId: string, workspaceId: string) => string;
+    /**
+     * Maximum number of Brainy instances to keep in memory simultaneously.
+     *
+     * When the limit is reached the least-recently-used instance is evicted.
+     * Defaults to `200` for per-user, `50` for per-tenant strategies.
+     */
+    maxInstances?: number;
+    /**
+     * Whether to call `brain.flush()` when an instance is evicted from the LRU.
+     *
+     * The flush is non-blocking from the pool's perspective — eviction completes
+     * immediately and the flush continues in the background.
+     *
+     * @default true
+     */
+    flushOnEvict?: boolean;
+    /**
+     * Optional async hook called after a new Brainy instance is initialized.
+     *
+     * Use this to run product-specific post-init logic: VFS integrity checks,
+     * data migrations, version tracking, plugin setup, etc. The brain is fully
+     * initialized before this callback fires and will be added to the pool after
+     * it resolves.
+     *
+     * If the callback throws, the init fails and the brain is not cached.
+     *
+     * @param brain - The newly initialized Brainy instance.
+     * @param storagePath - The filesystem path where this instance's data lives.
+     *
+     * @example Workshop VFS integrity check
+     * ```typescript
+     * onInit: async (brain, storagePath) => {
+     *   await verifyVFSIntegrity(brain, storagePath)
+     *   await migrateProjectMetadata(brain)
+     * }
+     * ```
+     */
+    onInit?: (brain: Brainy, storagePath: string) => Promise<void>;
+}
+/**
+ * Runtime statistics about the instance pool.
+ */
+export interface InstancePoolStats {
+    /** Number of instances currently in the cache. */
+    size: number;
+    /** Maximum number of instances the cache will hold. */
+    maxSize: number;
+    /** Scope keys of all currently cached instances. */
+    keys: string[];
+}
+/**
+ * LRU pool of live Brainy instances for server-mode SDK.
+ *
+ * Manages creation, caching, eviction, flushing, and graceful shutdown of
+ * Brainy instances. Supports per-user (Workshop), per-tenant (Venue), and
+ * per-scope (Academy / custom) pooling strategies.
+ *
+ * @example Workshop (per-user)
+ * ```typescript
+ * const pool = new BrainyInstancePool({
+ *   storage: 'mmap-filesystem',
+ *   dataPath: '/mnt/brainy-data',
+ *   strategy: 'per-user',
+ *   maxInstances: 200,
+ *   flushOnEvict: true,
+ * })
+ *
+ * const brain = await pool.forUser(emailHash, workspaceId)
+ * ```
+ *
+ * @example Venue (per-tenant)
+ * ```typescript
+ * const pool = new BrainyInstancePool({
+ *   storage: 'mmap-filesystem',
+ *   dataPath: '/mnt/brainy-data',
+ *   strategy: 'per-tenant',
+ *   maxInstances: 50,
+ *   flushOnEvict: true,
+ * })
+ *
+ * const brain = await pool.forTenant('wicks-and-whiskers')
+ * ```
+ */
+export declare class BrainyInstancePool {
+    private readonly config;
+    private readonly cache;
+    /** Deduplicates concurrent init requests for the same scope key. */
+    private readonly pending;
+    /**
+     * @param config - Pool configuration.
+     */
+    constructor(config: InstancePoolConfig);
+    /**
+     * Returns the Brainy instance for the given user and workspace.
+     *
+     * Uses `per-user` strategy: storage path is `{dataPath}/{emailHash}/{workspaceId}/`.
+     * The `userId` should be the SHA-256 email hash (8-char prefix) for path safety.
+     *
+     * @param userId - The user's email hash (e.g. from `computeEmailHash()`).
+     * @param workspaceId - The workspace identifier.
+     * @returns The cached or newly initialized Brainy instance.
+     * @throws Error if `strategy` is not `'per-user'`.
+     */
+    forUser(userId: string, workspaceId: string): Promise<Brainy>;
+    /**
+     * Returns the Brainy instance for the given tenant slug.
+     *
+     * Uses `per-tenant` strategy: storage path is `{dataPath}/{tenantSlug}/`.
+     *
+     * @param tenantSlug - The tenant identifier (URL-safe slug).
+     * @returns The cached or newly initialized Brainy instance.
+     * @throws Error if `strategy` is not `'per-tenant'`.
+     */
+    forTenant(tenantSlug: string): Promise<Brainy>;
+    /**
+     * Returns the Brainy instance for an arbitrary scope key.
+     *
+     * Uses `per-scope` strategy. The `factory` is called to create a Brainy instance
+     * if one does not already exist for `key`. The factory is called at most once per
+     * unique key — concurrent calls with the same key wait for the first creation.
+     *
+     * @param key - Unique stable string identifying this scope.
+     * @param factory - Async factory that creates a new Brainy instance for this scope.
+     * @returns The cached or newly created Brainy instance.
+     * @throws Error if `strategy` is not `'per-scope'`.
+     */
+    forScope(key: string, factory: () => Promise<Brainy>): Promise<Brainy>;
+    /**
+     * Flushes and removes a specific instance from the pool.
+     *
+     * Useful when a workspace is explicitly cleared or deleted.
+     *
+     * @param key - The scope key (as stored in the pool).
+     */
+    flush(key: string): Promise<void>;
+    /**
+     * Flushes all cached instances.
+     *
+     * Calls `brain.flush()` on every live instance. Does not remove them from the
+     * cache — they remain available for subsequent requests.
+     */
+    flushAll(): Promise<void>;
+    /**
+     * Gracefully shuts down the pool.
+     *
+     * Flushes all instances, then clears the cache. After `shutdown()`, the pool
+     * is empty and cannot be used without re-creating instances.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Returns current runtime statistics about the pool.
+     */
+    getStats(): InstancePoolStats;
+    /**
+     * Gets a cached Brainy instance by key, or creates and caches a new one.
+     *
+     * Concurrent calls with the same key wait for the first initialization
+     * rather than spawning duplicate Brainy instances.
+     *
+     * @param key - LRU cache key.
+     * @param storagePath - Filesystem path for this instance's Brainy data directory.
+     * @returns The cached or newly initialized Brainy instance.
+     */
+    private _getOrCreate;
+    /**
+     * Creates and initializes a Brainy instance at the given storage path.
+     *
+     * For `'mmap-filesystem'` storage the `@soulcraft/cortex` plugin is loaded
+     * automatically — Cortex intercepts Brainy's storage layer and upgrades it to
+     * native Rust mmap SSTables at runtime.
+     *
+     * @param storagePath - Absolute or relative path to the Brainy data directory.
+     * @returns A fully initialized Brainy instance.
+     */
+    private _initBrainy;
+}
+/**
+ * Thrown when a Brainy instance is still initializing and `waitForInit` is false.
+ *
+ * Products that want non-blocking behaviour (e.g. return HTTP 503 during cold
+ * start rather than waiting) can catch this error and respond with a
+ * `Retry-After` header using the suggested `retryAfter` value.
+ *
+ * @example
+ * ```typescript
+ * app.onError((err, c) => {
+ *   if (err instanceof BrainyInitializingError) {
+ *     return c.json({ error: 'Service starting', retryAfter: err.retryAfter }, 503, {
+ *       'Retry-After': String(err.retryAfter),
+ *     })
+ *   }
+ * })
+ * ```
+ */
+export declare class BrainyInitializingError extends Error {
+    /** Suggested number of seconds the client should wait before retrying. */
+    readonly retryAfter: number;
+    /**
+     * @param message - Error message.
+     * @param retryAfter - Suggested retry delay in seconds. Defaults to 5.
+     */
+    constructor(message: string, retryAfter?: number);
+}
+/**
+ * Computes an 8-character SHA-256 email hash used as the user-level directory
+ * component in `per-user` storage paths.
+ *
+ * Normalizes the email to lowercase + trimmed before hashing.
+ *
+ * @param email - The authenticated user's email address.
+ * @returns An 8-character lowercase hex string.
+ *
+ * @example
+ * ```typescript
+ * const hash = computeEmailHash('Alice@Workshop.soulcraft.com')
+ * // → 'a3f8c2b1' (deterministic)
+ * const brain = await pool.forUser(hash, workspaceId)
+ * ```
+ */
+export declare function computeEmailHash(email: string): string;
+//# sourceMappingURL=instance-pool.d.ts.map

package/dist/server/instance-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-pool.d.ts","sourceRoot":"","sources":["../../src/server/instance-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAMH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAMnD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,OAAO,EAAE,YAAY,GAAG,iBAAiB,CAAA;IAEzC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB,iCAAiC;IACjC,QAAQ,EAAE,gBAAgB,CAAA;IAE1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,CAAA;IAE1D;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IAEtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/D;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D;;OAEG;gBACS,MAAM,EAAE,kBAAkB;IA4BtC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASnE;;;;;;;;OAQG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASpD;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAyB5E;;;;;;OAMG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvC;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAY/B;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAM/B;;OAEG;IACH,QAAQ,IAAI,iBAAiB;IAU7B;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;IAqBpB;;;;;;;;;OASG;YACW,WAAW;CA0B1B;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,UAAU,SAAI;CAK5C;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/server/instance-pool.js

@@ -0,0 +1,359 @@
+/**
+ * @module server/instance-pool
+ * @description Brainy instance pool for server-mode SDK.
+ *
+ * Manages a pool of live Brainy instances using one of three strategies:
+ *
+ * - **`per-user`** (Workshop): one instance per `emailHash:workspaceId`. Storage path:
+ *   `{dataPath}/{emailHash}/{workspaceId}/`. Suited to many users each with their own
+ *   graph.
+ * - **`per-tenant`** (Venue): one instance per tenant slug. Storage path:
+ *   `{dataPath}/{tenantSlug}/`. The LRU max prevents memory exhaustion on high-traffic
+ *   installations.
+ * - **`per-scope`**: caller-supplied key function `scopeKey(userId, workspaceId)`. Covers
+ *   Academy and any bespoke use case.
+ *
+ * ## LRU eviction
+ *
+ * The pool is backed by `lru-cache`. When an entry is evicted (because the cache is
+ * full), the `dispose` callback fires synchronously. If `flushOnEvict` is `true`, a
+ * non-blocking `brain.flush()` call is queued — the eviction itself is not delayed.
+ * Call `flushAll()` or `shutdown()` before process exit to guarantee all writes are
+ * persisted.
+ *
+ * ## Concurrency
+ *
+ * Concurrent requests for the same scope key are deduplicated via a pending-init map.
+ * Only one Brainy instance is ever created per key, regardless of how many requests
+ * arrive simultaneously during cold start.
+ *
+ * @example
+ * ```typescript
+ * import { BrainyInstancePool } from '@soulcraft/sdk/server'
+ *
+ * const pool = new BrainyInstancePool({
+ *   storage: 'mmap-filesystem',
+ *   dataPath: '/mnt/brainy-data',
+ *   strategy: 'per-user',
+ *   maxInstances: 200,
+ *   flushOnEvict: true,
+ * })
+ *
+ * // In a request handler:
+ * const brain = await pool.forUser(session.user.emailHash, workspaceId)
+ * const results = await brain.find({ query: 'inventory items' })
+ * ```
+ */
+import { createHash } from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import { LRUCache } from 'lru-cache';
+import { Brainy } from '@soulcraft/brainy';
+// ─────────────────────────────────────────────────────────────────────────────
+// BrainyInstancePool
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * LRU pool of live Brainy instances for server-mode SDK.
+ *
+ * Manages creation, caching, eviction, flushing, and graceful shutdown of
+ * Brainy instances. Supports per-user (Workshop), per-tenant (Venue), and
+ * per-scope (Academy / custom) pooling strategies.
+ *
+ * @example Workshop (per-user)
+ * ```typescript
+ * const pool = new BrainyInstancePool({
+ *   storage: 'mmap-filesystem',
+ *   dataPath: '/mnt/brainy-data',
+ *   strategy: 'per-user',
+ *   maxInstances: 200,
+ *   flushOnEvict: true,
+ * })
+ *
+ * const brain = await pool.forUser(emailHash, workspaceId)
+ * ```
+ *
+ * @example Venue (per-tenant)
+ * ```typescript
+ * const pool = new BrainyInstancePool({
+ *   storage: 'mmap-filesystem',
+ *   dataPath: '/mnt/brainy-data',
+ *   strategy: 'per-tenant',
+ *   maxInstances: 50,
+ *   flushOnEvict: true,
+ * })
+ *
+ * const brain = await pool.forTenant('wicks-and-whiskers')
+ * ```
+ */
+export class BrainyInstancePool {
+    config;
+    cache;
+    /** Deduplicates concurrent init requests for the same scope key. */
+    pending = new Map();
+    /**
+     * @param config - Pool configuration.
+     */
+    constructor(config) {
+        const defaultMax = config.strategy === 'per-tenant' ? 50 : 200;
+        this.config = {
+            storage: config.storage,
+            dataPath: config.dataPath,
+            strategy: config.strategy,
+            scopeKey: config.scopeKey ?? ((userId, workspaceId) => `${userId}:${workspaceId}`),
+            maxInstances: config.maxInstances ?? defaultMax,
+            flushOnEvict: config.flushOnEvict ?? true,
+            onInit: config.onInit ?? (async () => { }),
+        };
+        this.cache = new LRUCache({
+            max: this.config.maxInstances,
+            dispose: (brain, _key, _reason) => {
+                if (this.config.flushOnEvict) {
+                    // Non-blocking flush — eviction is synchronous, flush runs in background.
+                    brain.flush().catch((err) => {
+                        console.error('[SDK/pool] flush-on-evict failed:', err);
+                    });
+                }
+            },
+        });
+    }
+    // ── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Returns the Brainy instance for the given user and workspace.
+     *
+     * Uses `per-user` strategy: storage path is `{dataPath}/{emailHash}/{workspaceId}/`.
+     * The `userId` should be the SHA-256 email hash (8-char prefix) for path safety.
+     *
+     * @param userId - The user's email hash (e.g. from `computeEmailHash()`).
+     * @param workspaceId - The workspace identifier.
+     * @returns The cached or newly initialized Brainy instance.
+     * @throws Error if `strategy` is not `'per-user'`.
+     */
+    async forUser(userId, workspaceId) {
+        if (this.config.strategy !== 'per-user') {
+            throw new Error(`BrainyInstancePool.forUser() called but strategy is '${this.config.strategy}'`);
+        }
+        const key = `${userId}:${workspaceId}`;
+        const storagePath = path.join(this.config.dataPath, userId, workspaceId);
+        return this._getOrCreate(key, storagePath);
+    }
+    /**
+     * Returns the Brainy instance for the given tenant slug.
+     *
+     * Uses `per-tenant` strategy: storage path is `{dataPath}/{tenantSlug}/`.
+     *
+     * @param tenantSlug - The tenant identifier (URL-safe slug).
+     * @returns The cached or newly initialized Brainy instance.
+     * @throws Error if `strategy` is not `'per-tenant'`.
+     */
+    async forTenant(tenantSlug) {
+        if (this.config.strategy !== 'per-tenant') {
+            throw new Error(`BrainyInstancePool.forTenant() called but strategy is '${this.config.strategy}'`);
+        }
+        const key = tenantSlug;
+        const storagePath = path.join(this.config.dataPath, tenantSlug);
+        return this._getOrCreate(key, storagePath);
+    }
+    /**
+     * Returns the Brainy instance for an arbitrary scope key.
+     *
+     * Uses `per-scope` strategy. The `factory` is called to create a Brainy instance
+     * if one does not already exist for `key`. The factory is called at most once per
+     * unique key — concurrent calls with the same key wait for the first creation.
+     *
+     * @param key - Unique stable string identifying this scope.
+     * @param factory - Async factory that creates a new Brainy instance for this scope.
+     * @returns The cached or newly created Brainy instance.
+     * @throws Error if `strategy` is not `'per-scope'`.
+     */
+    async forScope(key, factory) {
+        if (this.config.strategy !== 'per-scope') {
+            throw new Error(`BrainyInstancePool.forScope() called but strategy is '${this.config.strategy}'`);
+        }
+        const cached = this.cache.get(key);
+        if (cached)
+            return cached;
+        if (this.pending.has(key)) {
+            return this.pending.get(key);
+        }
+        const initPromise = factory().then((brain) => {
+            this.cache.set(key, brain);
+            this.pending.delete(key);
+            return brain;
+        }).catch((err) => {
+            this.pending.delete(key);
+            throw err;
+        });
+        this.pending.set(key, initPromise);
+        return initPromise;
+    }
+    /**
+     * Flushes and removes a specific instance from the pool.
+     *
+     * Useful when a workspace is explicitly cleared or deleted.
+     *
+     * @param key - The scope key (as stored in the pool).
+     */
+    async flush(key) {
+        const brain = this.cache.get(key);
+        if (!brain)
+            return;
+        try {
+            await brain.flush();
+        }
+        finally {
+            this.cache.delete(key);
+        }
+    }
+    /**
+     * Flushes all cached instances.
+     *
+     * Calls `brain.flush()` on every live instance. Does not remove them from the
+     * cache — they remain available for subsequent requests.
+     */
+    async flushAll() {
+        const flushes = [];
+        for (const brain of this.cache.values()) {
+            flushes.push(brain.flush().catch((err) => {
+                console.error('[SDK/pool] flushAll error:', err);
+            }));
+        }
+        await Promise.all(flushes);
+    }
+    /**
+     * Gracefully shuts down the pool.
+     *
+     * Flushes all instances, then clears the cache. After `shutdown()`, the pool
+     * is empty and cannot be used without re-creating instances.
+     */
+    async shutdown() {
+        await this.flushAll();
+        this.cache.clear();
+        this.pending.clear();
+    }
+    /**
+     * Returns current runtime statistics about the pool.
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.config.maxInstances,
+            keys: [...this.cache.keys()],
+        };
+    }
+    // ── Internal ───────────────────────────────────────────────────────────────
+    /**
+     * Gets a cached Brainy instance by key, or creates and caches a new one.
+     *
+     * Concurrent calls with the same key wait for the first initialization
+     * rather than spawning duplicate Brainy instances.
+     *
+     * @param key - LRU cache key.
+     * @param storagePath - Filesystem path for this instance's Brainy data directory.
+     * @returns The cached or newly initialized Brainy instance.
+     */
+    _getOrCreate(key, storagePath) {
+        const cached = this.cache.get(key);
+        if (cached)
+            return Promise.resolve(cached);
+        if (this.pending.has(key)) {
+            return this.pending.get(key);
+        }
+        const initPromise = this._initBrainy(storagePath).then((brain) => {
+            this.cache.set(key, brain);
+            this.pending.delete(key);
+            return brain;
+        }).catch((err) => {
+            this.pending.delete(key);
+            throw err;
+        });
+        this.pending.set(key, initPromise);
+        return initPromise;
+    }
+    /**
+     * Creates and initializes a Brainy instance at the given storage path.
+     *
+     * For `'mmap-filesystem'` storage the `@soulcraft/cortex` plugin is loaded
+     * automatically — Cortex intercepts Brainy's storage layer and upgrades it to
+     * native Rust mmap SSTables at runtime.
+     *
+     * @param storagePath - Absolute or relative path to the Brainy data directory.
+     * @returns A fully initialized Brainy instance.
+     */
+    async _initBrainy(storagePath) {
+        await fs.mkdir(storagePath, { recursive: true });
+        const initStart = Date.now();
+        const brain = new Brainy({
+            storage: {
+                type: 'filesystem',
+                options: { rootDirectory: storagePath },
+            },
+            plugins: this.config.storage === 'mmap-filesystem'
+                ? ['@soulcraft/cortex']
+                : [],
+        });
+        await brain.init();
+        if (this.config.onInit) {
+            await this.config.onInit(brain, storagePath);
+        }
+        const elapsed = Date.now() - initStart;
+        console.log(`[SDK/pool] Brainy ready: ${path.basename(storagePath)} (${elapsed}ms) [${this.config.storage}]`);
+        return brain;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// BrainyInitializingError
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Thrown when a Brainy instance is still initializing and `waitForInit` is false.
+ *
+ * Products that want non-blocking behaviour (e.g. return HTTP 503 during cold
+ * start rather than waiting) can catch this error and respond with a
+ * `Retry-After` header using the suggested `retryAfter` value.
+ *
+ * @example
+ * ```typescript
+ * app.onError((err, c) => {
+ *   if (err instanceof BrainyInitializingError) {
+ *     return c.json({ error: 'Service starting', retryAfter: err.retryAfter }, 503, {
+ *       'Retry-After': String(err.retryAfter),
+ *     })
+ *   }
+ * })
+ * ```
+ */
+export class BrainyInitializingError extends Error {
+    /** Suggested number of seconds the client should wait before retrying. */
+    retryAfter;
+    /**
+     * @param message - Error message.
+     * @param retryAfter - Suggested retry delay in seconds. Defaults to 5.
+     */
+    constructor(message, retryAfter = 5) {
+        super(message);
+        this.name = 'BrainyInitializingError';
+        this.retryAfter = retryAfter;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Computes an 8-character SHA-256 email hash used as the user-level directory
+ * component in `per-user` storage paths.
+ *
+ * Normalizes the email to lowercase + trimmed before hashing.
+ *
+ * @param email - The authenticated user's email address.
+ * @returns An 8-character lowercase hex string.
+ *
+ * @example
+ * ```typescript
+ * const hash = computeEmailHash('Alice@Workshop.soulcraft.com')
+ * // → 'a3f8c2b1' (deterministic)
+ * const brain = await pool.forUser(hash, workspaceId)
+ * ```
+ */
+export function computeEmailHash(email) {
+    return createHash('sha256').update(email.toLowerCase().trim()).digest('hex').substring(0, 8);
+}
+//# sourceMappingURL=instance-pool.js.map

package/dist/server/instance-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-pool.js","sourceRoot":"","sources":["../../src/server/instance-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACnC,OAAO,EAAE,MAAM,aAAa,CAAA;AAC5B,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAmG1C,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,kBAAkB;IACZ,MAAM,CAA8B;IACpC,KAAK,CAA0B;IAChD,oEAAoE;IACnD,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAA;IAE7D;;OAEG;IACH,YAAY,MAA0B;QACpC,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAA;QAE9D,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,CAAC,GAAG,MAAM,IAAI,WAAW,EAAE,CAAC;YAClF,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,UAAU;YAC/C,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;YACzC,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC;SAC1C,CAAA;QAED,IAAI,CAAC,KAAK,GAAG,IAAI,QAAQ,CAAiB;YACxC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;YAC7B,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;gBAChC,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;oBAC7B,0EAA0E;oBAC1E,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;wBAC1B,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE,GAAG,CAAC,CAAA;oBACzD,CAAC,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC;SACF,CAAC,CAAA;IACJ,CAAC;IAED,8EAA8E;IAE9E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,WAAmB;QAC/C,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,wDAAwD,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAA;QAClG,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,WAAW,EAAE,CAAA;QACtC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,CAAA;QACxE,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,WAAW,CAAC,CAAA;IAC5C,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,CAAC,UAAkB;QAChC,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,0DAA0D,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAA;QACpG,CAAC;QACD,MAAM,GAAG,GAAG,UAAU,CAAA;QACtB,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;QAC/D,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,WAAW,CAAC,CAAA;IAC5C,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,CAAC,GAAW,EAAE,OAA8B;QACxD,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CAAC,yDAAyD,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAA;QACnG,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,MAAM;YAAE,OAAO,MAAM,CAAA;QAEzB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAE,CAAA;QAC/B,CAAC;QAED,MAAM,WAAW,GAAG,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;YAC3C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACxB,OAAO,KAAK,CAAA;QACd,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACf,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACxB,MAAM,GAAG,CAAA;QACX,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAA;QAClC,OAAO,WAAW,CAAA;IACpB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,GAAW;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACjC,IAAI,CAAC,KAAK;YAAE,OAAM;QAClB,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,KAAK,EAAE,CAAA;QACrB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACxB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,OAAO,GAAoB,EAAE,CAAA;QACnC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACxC,OAAO,CAAC,IAAI,CACV,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBAC1B,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,GAAG,CAAC,CAAA;YAClD,CAAC,CAAC,CACH,CAAA;QACH,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC5B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAA;QACrB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAA;QAClB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACrB,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;YACjC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC7B,CAAA;IACH,CAAC;IAED,8EAA8E;IAE9E;;;;;;;;;OASG;IACK,YAAY,CAAC,GAAW,EAAE,WAAmB;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,MAAM;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QAE1C,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAE,CAAA;QAC/B,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;YAC/D,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACxB,OAAO,KAAK,CAAA;QACd,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACf,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACxB,MAAM,GAAG,CAAA;QACX,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAA;QAClC,OAAO,WAAW,CAAA;IACpB,CAAC;IAED;;;;;;;;;OASG;IACK,KAAK,CAAC,WAAW,CAAC,WAAmB;QAC3C,MAAM,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAEhD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAC5B,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC;YACvB,OAAO,EAAE;gBACP,IAAI,EAAE,YAAY;gBAClB,OAAO,EAAE,EAAE,aAAa,EAAE,WAAW,EAAE;aACxC;YACD,OAAO,EACL,IAAI,CAAC,MAAM,CAAC,OAAO,KAAK,iBAAiB;gBACvC,CAAC,CAAC,CAAC,mBAAmB,CAAC;gBACvB,CAAC,CAAC,EAAE;SACT,CAAC,CAAA;QAEF,MAAM,KAAK,CAAC,IAAI,EAAE,CAAA;QAElB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACvB,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,CAAA;QAC9C,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAA;QACtC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,OAAO,QAAQ,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,CAAA;QAE7G,OAAO,KAAK,CAAA;IACd,CAAC;CACF;AAED,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,0EAA0E;IACjE,UAAU,CAAQ;IAE3B;;;OAGG;IACH,YAAY,OAAe,EAAE,UAAU,GAAG,CAAC;QACzC,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;QACrC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;CACF;AAED,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AAC9F,CAAC"}