@maadb/core 0.0.1 → 0.7.10-rc.3

package/dist/instance/pool.js

@@ -0,0 +1,335 @@
+// ============================================================================
+// EnginePool — lazy, per-project MaadEngine cache for multi-project routing
+//
+// First call to get(name) initializes the engine and scaffolds _skills/.
+// Subsequent calls return the cached engine. evict(name) is a public seam
+// for future policies (LRU/TTL) layered in 0.9.0; v1 never calls it from
+// inside the pool.
+//
+// reloadInstance(newInstance) swaps the live instance config, applying
+// project additions (lazy — just make them declarable) and removals (evict
+// engines + callbacks for session cancellation). Mutations of existing
+// projects' path/role fail the whole reload with INSTANCE_MUTATION_UNSUPPORTED;
+// that seam opens when the 0.9.0 eviction policy lands.
+// ============================================================================
+import { MaadEngine } from '../engine/index.js';
+import { ensureProjectSkills } from '../skills-scaffold.js';
+import { ok, singleErr } from '../errors.js';
+import { getProject } from './config.js';
+export class EnginePool {
+    instance;
+    engines = new Map();
+    initPromises = new Map();
+    reloadInFlight = false;
+    stats = {
+        lastReloadAt: null,
+        reloadsAttempted: 0,
+        reloadsSucceeded: 0,
+        reloadsFailed: 0,
+        projectsAdded: 0,
+        projectsRemoved: 0,
+    };
+    // 0.7.3 — Idle-timeout eviction state. lastTouchedAt is bumped on every
+    // successful get(); refcount is bumped by acquire() / decremented by
+    // release() so the sweeper never evicts a project with in-flight ops.
+    lastTouchedAt = new Map();
+    refcount = new Map();
+    sweepHandle = null;
+    sweepConfig = null;
+    evictionStats = {
+        evictionsTotal: 0,
+        lastEvictionAt: null,
+        lastEvictionProjects: [],
+        sweepsRun: 0,
+        lastSweepAt: null,
+    };
+    nowFn = Date.now;
+    constructor(instance) {
+        this.instance = instance;
+    }
+    /** Test seam — override the time source so sweeper logic is testable. */
+    setNowFn(fn) {
+        this.nowFn = fn;
+    }
+    getInstance() {
+        return this.instance;
+    }
+    listProjects() {
+        return [...this.instance.projects];
+    }
+    has(name) {
+        return this.engines.has(name);
+    }
+    reloadStats() {
+        return { ...this.stats };
+    }
+    // Returns the cached engine or initializes it. Concurrent calls for the
+    // same project await the same init promise so we don't double-init.
+    async get(name) {
+        const cached = this.engines.get(name);
+        if (cached) {
+            this.lastTouchedAt.set(name, this.nowFn());
+            return ok(cached);
+        }
+        const inFlight = this.initPromises.get(name);
+        if (inFlight) {
+            const r = await inFlight;
+            if (r.ok)
+                this.lastTouchedAt.set(name, this.nowFn());
+            return r;
+        }
+        const project = getProject(this.instance, name);
+        if (!project) {
+            return singleErr('PROJECT_UNKNOWN', `Project "${name}" is not declared in instance "${this.instance.name}"`);
+        }
+        const initPromise = this.initEngine(project);
+        this.initPromises.set(name, initPromise);
+        try {
+            const result = await initPromise;
+            if (result.ok) {
+                this.engines.set(name, result.value);
+                this.lastTouchedAt.set(name, this.nowFn());
+            }
+            return result;
+        }
+        finally {
+            this.initPromises.delete(name);
+        }
+    }
+    /**
+     * 0.7.3 — In-flight refcount. Caller increments before invoking the
+     * handler, decrements in finally. The idle sweeper refuses to evict any
+     * project with refcount > 0.
+     */
+    acquire(name) {
+        this.refcount.set(name, (this.refcount.get(name) ?? 0) + 1);
+        this.lastTouchedAt.set(name, this.nowFn());
+    }
+    release(name) {
+        const cur = this.refcount.get(name) ?? 0;
+        if (cur <= 1) {
+            this.refcount.delete(name);
+        }
+        else {
+            this.refcount.set(name, cur - 1);
+        }
+        this.lastTouchedAt.set(name, this.nowFn());
+    }
+    refcountFor(name) {
+        return this.refcount.get(name) ?? 0;
+    }
+    lastTouchedFor(name) {
+        return this.lastTouchedAt.get(name) ?? null;
+    }
+    async initEngine(project) {
+        const engine = new MaadEngine();
+        const initResult = await engine.init(project.path);
+        if (!initResult.ok)
+            return initResult;
+        ensureProjectSkills(project.path);
+        return ok(engine);
+    }
+    // Public eviction seam. 0.7.3 — also called by the idle sweeper. Closes
+    // SQLite cleanly before removing. Refcount-protected callers should check
+    // refcount before calling; this method is unconditional.
+    async evict(name) {
+        const engine = this.engines.get(name);
+        if (!engine)
+            return;
+        engine.close();
+        this.engines.delete(name);
+        this.lastTouchedAt.delete(name);
+        this.refcount.delete(name);
+    }
+    /**
+     * 0.7.3 — Idle eviction sweep. Returns the names of projects evicted in
+     * this sweep. Skips projects with refcount > 0 (in-flight ops) and any
+     * project whose lastTouchedAt is missing (defensive — would mean it's not
+     * actually loaded). idleTimeoutMs=0 is a no-op (eviction disabled).
+     */
+    async evictIdle(idleTimeoutMs) {
+        this.evictionStats.sweepsRun++;
+        this.evictionStats.lastSweepAt = new Date(this.nowFn());
+        if (idleTimeoutMs <= 0)
+            return [];
+        const now = this.nowFn();
+        const candidates = [];
+        for (const name of this.engines.keys()) {
+            if ((this.refcount.get(name) ?? 0) > 0)
+                continue;
+            const touched = this.lastTouchedAt.get(name);
+            if (touched === undefined)
+                continue;
+            if (now - touched >= idleTimeoutMs)
+                candidates.push(name);
+        }
+        for (const name of candidates)
+            await this.evict(name);
+        if (candidates.length > 0) {
+            this.evictionStats.evictionsTotal += candidates.length;
+            this.evictionStats.lastEvictionAt = new Date(now);
+            this.evictionStats.lastEvictionProjects = candidates;
+        }
+        return candidates;
+    }
+    /**
+     * 0.7.3 — Start the background idle sweeper. Idempotent — calling twice
+     * replaces the existing schedule. Use stopIdleSweeper() during shutdown.
+     * Sweep timer is unref()'d so it never blocks process exit.
+     */
+    startIdleSweeper(config) {
+        this.stopIdleSweeper();
+        this.sweepConfig = config;
+        if (config.idleTimeoutMs <= 0 || config.sweepIntervalMs <= 0)
+            return;
+        this.sweepHandle = setInterval(() => {
+            void this.evictIdle(config.idleTimeoutMs).catch(() => { });
+        }, config.sweepIntervalMs);
+        if (typeof this.sweepHandle.unref === 'function')
+            this.sweepHandle.unref();
+    }
+    stopIdleSweeper() {
+        if (this.sweepHandle) {
+            clearInterval(this.sweepHandle);
+            this.sweepHandle = null;
+        }
+        this.sweepConfig = null;
+    }
+    evictionStatsSnapshot() {
+        return { ...this.evictionStats, lastEvictionProjects: [...this.evictionStats.lastEvictionProjects] };
+    }
+    idleSweepConfig() {
+        return this.sweepConfig ? { ...this.sweepConfig } : null;
+    }
+    static readIdleSweepEnv(env = process.env) {
+        // Default: 30 min idle timeout, 60s sweep interval. Set
+        // MAAD_PROJECT_IDLE_TIMEOUT_MS=0 to disable.
+        const idleRaw = env.MAAD_PROJECT_IDLE_TIMEOUT_MS;
+        const sweepRaw = env.MAAD_PROJECT_SWEEP_INTERVAL_MS;
+        const idle = idleRaw !== undefined ? Number.parseInt(idleRaw, 10) : 30 * 60 * 1000;
+        const sweep = sweepRaw !== undefined ? Number.parseInt(sweepRaw, 10) : 60 * 1000;
+        return {
+            idleTimeoutMs: Number.isFinite(idle) && idle >= 0 ? idle : 30 * 60 * 1000,
+            sweepIntervalMs: Number.isFinite(sweep) && sweep > 0 ? sweep : 60 * 1000,
+        };
+    }
+    async closeAll() {
+        this.stopIdleSweeper();
+        for (const [name, engine] of this.engines) {
+            try {
+                engine.close();
+            }
+            catch {
+                // swallow — shutdown best-effort
+            }
+            this.engines.delete(name);
+        }
+        this.lastTouchedAt.clear();
+        this.refcount.clear();
+    }
+    /**
+     * Sum of `writeQueueDepth()` across every initialized engine. Used by the
+     * shutdown drain loop to know when it's safe to exit. Uninitialized engines
+     * contribute 0 and are not lazy-initialized.
+     */
+    totalWriteQueueDepth() {
+        let total = 0;
+        for (const engine of this.engines.values()) {
+            total += engine.writeQueueDepth();
+        }
+        return total;
+    }
+    /**
+     * Atomic reload slot — acquired before any I/O (config parse), released
+     * after diff + stats are recorded. The orchestrator in
+     * `src/mcp/instance-reload.ts` holds this for the lifetime of the reload
+     * so concurrent callers fail fast with INSTANCE_RELOAD_IN_PROGRESS instead
+     * of racing to swap the instance ref.
+     *
+     * Returns false if a reload is already in progress or the instance is
+     * synthetic (tested separately so the error code can be distinguished).
+     */
+    tryBeginReload() {
+        if (this.instance.source === 'synthetic') {
+            return { ok: false, code: 'INSTANCE_RELOAD_SYNTHETIC' };
+        }
+        if (this.reloadInFlight) {
+            return { ok: false, code: 'INSTANCE_RELOAD_IN_PROGRESS' };
+        }
+        this.reloadInFlight = true;
+        this.stats.reloadsAttempted++;
+        return { ok: true };
+    }
+    /**
+     * Release the reload slot. Called by the orchestrator in a `finally` so
+     * success + failure paths both land here. Updates the success/failure
+     * counters + project-diff stats.
+     */
+    endReload(outcome) {
+        if (outcome.ok) {
+            this.stats.reloadsSucceeded++;
+            this.stats.lastReloadAt = new Date();
+            this.stats.projectsAdded += outcome.diff.added.length;
+            this.stats.projectsRemoved += outcome.diff.removed.length;
+        }
+        else {
+            this.stats.reloadsFailed++;
+        }
+        this.reloadInFlight = false;
+    }
+    /**
+     * Apply a parsed instance config: detect mutations (fail-fast, no partial),
+     * evict engines for removed projects, swap the internal instance ref.
+     * Must be called between `tryBeginReload` and `endReload` — does not manage
+     * the reload slot itself.
+     *
+     * Mutations (same name, different path or role) fail the whole reload with
+     * INSTANCE_MUTATION_UNSUPPORTED — no partial apply. The 0.9.0 eviction
+     * policy unlocks safe in-place project mutations.
+     */
+    async applyDiff(newInstance) {
+        const oldByName = new Map(this.instance.projects.map(p => [p.name, p]));
+        const newByName = new Map(newInstance.projects.map(p => [p.name, p]));
+        // Detect mutations first — fail fast before touching state.
+        const mutations = [];
+        for (const [name, oldP] of oldByName) {
+            const newP = newByName.get(name);
+            if (!newP)
+                continue; // removal, handled below
+            if (oldP.path !== newP.path || oldP.role !== newP.role) {
+                mutations.push(`"${name}" (${oldP.path}/${oldP.role} → ${newP.path}/${newP.role})`);
+            }
+        }
+        if (mutations.length > 0) {
+            return singleErr('INSTANCE_MUTATION_UNSUPPORTED', `Cannot mutate existing projects in place (path/role change). Affected: ${mutations.join(', ')}. Remove and re-add, or wait for 0.9.0 eviction policy.`);
+        }
+        const added = [];
+        const removed = [];
+        for (const name of newByName.keys()) {
+            if (!oldByName.has(name))
+                added.push(name);
+        }
+        for (const name of oldByName.keys()) {
+            if (!newByName.has(name))
+                removed.push(name);
+        }
+        // Evict removed engines. Do this BEFORE swapping the instance ref so
+        // getProject() during evict still sees the old config (not strictly
+        // required — evict only uses `name` — but preserves invariant).
+        for (const name of removed) {
+            await this.evict(name);
+        }
+        // Atomic swap: instance ref + downstream refs (caller's responsibility
+        // to propagate to SessionRegistry + InstanceCtx).
+        this.instance = newInstance;
+        return ok({ added, removed });
+    }
+    /**
+     * Swap the instance config without diff/eviction. Used by the reload
+     * orchestrator if it needs to keep downstream refs in sync, or by tests.
+     */
+    setInstance(newInstance) {
+        this.instance = newInstance;
+    }
+}
+//# sourceMappingURL=pool.js.map

package/dist/instance/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/instance/pool.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,4EAA4E;AAC5E,EAAE;AACF,yEAAyE;AACzE,0EAA0E;AAC1E,yEAAyE;AACzE,mBAAmB;AACnB,EAAE;AACF,uEAAuE;AACvE,2EAA2E;AAC3E,uEAAuE;AACvE,gFAAgF;AAChF,wDAAwD;AACxD,+EAA+E;AAE/E,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,EAAE,EAAE,SAAS,EAAe,MAAM,cAAc,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAyCzC,MAAM,OAAO,UAAU;IA6BD;IA5BZ,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IACxC,YAAY,GAAG,IAAI,GAAG,EAAuC,CAAC;IAC9D,cAAc,GAAG,KAAK,CAAC;IACvB,KAAK,GAAwB;QACnC,YAAY,EAAE,IAAI;QAClB,gBAAgB,EAAE,CAAC;QACnB,gBAAgB,EAAE,CAAC;QACnB,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,CAAC;QAChB,eAAe,EAAE,CAAC;KACnB,CAAC;IAEF,wEAAwE;IACxE,qEAAqE;IACrE,sEAAsE;IAC9D,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,WAAW,GAA0B,IAAI,CAAC;IAC1C,WAAW,GAA2B,IAAI,CAAC;IAC3C,aAAa,GAAkB;QACrC,cAAc,EAAE,CAAC;QACjB,cAAc,EAAE,IAAI;QACpB,oBAAoB,EAAE,EAAE;QACxB,SAAS,EAAE,CAAC;QACZ,WAAW,EAAE,IAAI;KAClB,CAAC;IACM,KAAK,GAAiB,IAAI,CAAC,GAAG,CAAC;IAEvC,YAAoB,QAAwB;QAAxB,aAAQ,GAAR,QAAQ,CAAgB;IAAG,CAAC;IAEhD,yEAAyE;IACzE,QAAQ,CAAC,EAAgB;QACvB,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,YAAY;QACV,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,WAAW;QACT,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED,wEAAwE;IACxE,oEAAoE;IACpE,KAAK,CAAC,GAAG,CAAC,IAAY;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YAC3C,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;QACpB,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,MAAM,QAAQ,CAAC;YACzB,IAAI,CAAC,CAAC,EAAE;gBAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YACrD,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,SAAS,CAAC,iBAAiB,EAAE,YAAY,IAAI,kCAAkC,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC;QAC/G,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACzC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC;YACjC,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACd,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;gBACrC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YAC7C,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5D,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;YACb,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,WAAW,CAAC,IAAY;QACtB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,cAAc,CAAC,IAAY;QACzB,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IAC9C,CAAC;IAEO,KAAK,CAAC,UAAU,CAAC,OAAsB;QAC7C,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAChC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,CAAC,UAAU,CAAC,EAAE;YAAE,OAAO,UAAU,CAAC;QACtC,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;IAED,wEAAwE;IACxE,0EAA0E;IAC1E,yDAAyD;IACzD,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS,CAAC,aAAqB;QACnC,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,CAAC;QAC/B,IAAI,CAAC,aAAa,CAAC,WAAW,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACxD,IAAI,aAAa,IAAI,CAAC;YAAE,OAAO,EAAE,CAAC;QAElC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACzB,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;YACvC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;gBAAE,SAAS;YACjD,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC7C,IAAI,OAAO,KAAK,SAAS;gBAAE,SAAS;YACpC,IAAI,GAAG,GAAG,OAAO,IAAI,aAAa;gBAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5D,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,UAAU;YAAE,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAEtD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,aAAa,CAAC,cAAc,IAAI,UAAU,CAAC,MAAM,CAAC;YACvD,IAAI,CAAC,aAAa,CAAC,cAAc,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;YAClD,IAAI,CAAC,aAAa,CAAC,oBAAoB,GAAG,UAAU,CAAC;QACvD,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;;OAIG;IACH,gBAAgB,CAAC,MAAuB;QACtC,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC;QAC1B,IAAI,MAAM,CAAC,aAAa,IAAI,CAAC,IAAI,MAAM,CAAC,eAAe,IAAI,CAAC;YAAE,OAAO;QACrE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE;YAClC,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAgC,CAAC,CAAC,CAAC;QAC1F,CAAC,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;QAC3B,IAAI,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,KAAK,UAAU;YAAE,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC7E,CAAC;IAED,eAAe;QACb,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAChC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED,qBAAqB;QACnB,OAAO,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,oBAAoB,EAAE,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,oBAAoB,CAAC,EAAE,CAAC;IACvG,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3D,CAAC;IAED,MAAM,CAAC,gBAAgB,CAAC,MAAyB,OAAO,CAAC,GAAG;QAC1D,wDAAwD;QACxD,6CAA6C;QAC7C,MAAM,OAAO,GAAG,GAAG,CAAC,4BAA4B,CAAC;QACjD,MAAM,QAAQ,GAAG,GAAG,CAAC,8BAA8B,CAAC;QACpD,MAAM,IAAI,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QACnF,MAAM,KAAK,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC;QACjF,OAAO;YACL,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI;YACzE,eAAe,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI;SACzE,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC1C,IAAI,CAAC;gBACH,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,CAAC;YAAC,MAAM,CAAC;gBACP,iCAAiC;YACnC,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACH,oBAAoB;QAClB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,KAAK,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;QACpC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;;OASG;IACH,cAAc;QACZ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACzC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,2BAA2B,EAAE,CAAC;QAC1D,CAAC;QACD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,6BAA6B,EAAE,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC9B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,OAAyD;QACjE,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC;YAC9B,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,IAAI,EAAE,CAAC;YACrC,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YACtD,IAAI,CAAC,KAAK,CAAC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QAC5D,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;QAC7B,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,SAAS,CAAC,WAA2B;QACzC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAU,CAAC,CAAC,CAAC;QACjF,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAU,CAAC,CAAC,CAAC;QAE/E,4DAA4D;QAC5D,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACjC,IAAI,CAAC,IAAI;gBAAE,SAAS,CAAC,yBAAyB;YAC9C,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;gBACvD,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,MAAM,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;YACtF,CAAC;QACH,CAAC;QACD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,OAAO,SAAS,CAAC,+BAA+B,EAC9C,0EAA0E,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;QAC7J,CAAC;QAED,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC;QAED,qEAAqE;QACrE,oEAAoE;QACpE,gEAAgE;QAChE,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QAED,uEAAuE;QACvE,kDAAkD;QAClD,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC;QAE5B,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,WAAW,CAAC,WAA2B;QACrC,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC;IAC9B,CAAC;CACF"}

package/dist/instance/session.d.ts

@@ -0,0 +1,140 @@
+import { type Result } from '../errors.js';
+import { type Role } from '../mcp/roles.js';
+import type { InstanceConfig } from './config.js';
+import type { TokenRecord } from '../auth/types.js';
+export type SessionMode = 'single' | 'multi';
+/**
+ * How a session was bound to its project(s). Load-bearing for gateway-pinned
+ * sessions: rebind-rejection in maad_use_project/maad_use_projects checks
+ * `bindingSource === 'gateway_pin'` to distinguish trusted-gateway pins from
+ * client-initiated binds. `null` = session exists but is unbound.
+ *
+ * - `client_tool`  — bound by client calling maad_use_project/maad_use_projects
+ * - `gateway_pin`  — bound by HTTP transport honoring X-Maad-Pin-Project header
+ *                    (multi-tenant hosted deployments, 0.6.8+); irrevocable
+ */
+export type BindingSource = 'client_tool' | 'gateway_pin';
+export interface SessionState {
+    sessionId: string;
+    mode: SessionMode | null;
+    activeProject?: string;
+    whitelist?: string[];
+    effectiveRoles: Map<string, Role>;
+    bindingSource: BindingSource | null;
+    createdAt: Date;
+    lastActivityAt: Date;
+    /**
+     * Set to true by `cancelByProject` when the session's bound project was
+     * removed via instance reload. The next tool call checks this flag and
+     * returns SESSION_CANCELLED, then destroys the session. Multi-mode sessions
+     * whose whitelist merely contained the removed project are NOT cancelled —
+     * their whitelist is pruned via `pruneProjectFromWhitelist` instead.
+     */
+    cancelled?: boolean;
+    /**
+     * 0.6.11 — Live notification subscription. Set by `maad_subscribe`,
+     * cleared by `maad_unsubscribe` or session destroy. When present, durable
+     * writes matching the filter fire `notifications/resources/updated` to
+     * this session via its registered notifier (see NotifierRegistry).
+     * docTypes null = match all types; project null = match the session's
+     * bound project (single-mode) or any project in the whitelist (multi-mode).
+     */
+    subscription?: {
+        docTypes: string[] | null;
+        project: string | null;
+        createdAt: Date;
+    };
+    /**
+     * 0.7.0 — The token record resolved from the Authorization header at
+     * session initialize (HTTP+registry mode only). undefined in stdio /
+     * synthetic / legacy modes (which don't have a bearer channel). Used by
+     * bindSingle/bindMulti for three-cap effective-role composition, and by
+     * audit log identity propagation (P3).
+     */
+    token?: TokenRecord;
+}
+export interface BindOptions {
+    as?: Role;
+    /**
+     * Who initiated the bind. Defaults to `client_tool`. HTTP transport passes
+     * `gateway_pin` when the X-Maad-Pin-Project header was honored at initialize.
+     * Once a session is bound with `gateway_pin`, rebind attempts via
+     * maad_use_project/maad_use_projects reject with SESSION_PINNED.
+     */
+    source?: BindingSource;
+}
+export type SessionCloseReason = 'client' | 'transport' | 'idle' | 'shutdown';
+export type SessionCloseHandler = (sessionId: string, reason: SessionCloseReason) => void;
+export type SessionCreateHandler = (sessionId: string) => void;
+export declare class SessionRegistry {
+    private instance;
+    private sessions;
+    private closeHandlers;
+    private createHandlers;
+    constructor(instance: InstanceConfig);
+    /**
+     * Swap the live instance config. Called by the instance-reload path after
+     * the pool has applied diffs. Does not touch existing sessions — cancellation
+     * and whitelist pruning are separate explicit calls.
+     */
+    setInstance(newInstance: InstanceConfig): void;
+    create(sessionId: string): SessionState;
+    get(sessionId: string): SessionState | undefined;
+    /**
+     * Peek without bumping lastActivityAt. Used by the idle sweeper — it must
+     * not reset the very activity timestamp it's checking against.
+     */
+    peek(sessionId: string): SessionState | undefined;
+    /**
+     * Register a handler fired when a session is destroyed, regardless of cause.
+     * Handlers should be cheap (syncronous, no throws); failures in one handler
+     * must not block others. Multiple handlers compose in registration order.
+     */
+    registerCloseHandler(handler: SessionCloseHandler): void;
+    /**
+     * 0.6.11 — Register a handler fired when a session is created. Used by
+     * stdio mode to register a notifier once the synthesized stdio session ID
+     * becomes known (HTTP knows the sid earlier via onsessioninitialized).
+     * Same best-effort / non-throwing contract as closeHandlers.
+     */
+    registerCreateHandler(handler: SessionCreateHandler): void;
+    destroy(sessionId: string, reason?: SessionCloseReason): void;
+    size(): number;
+    /**
+     * Iterate session snapshots without triggering lastActivityAt updates.
+     * Returned array is a copy — safe to mutate during iteration (the sweeper
+     * calls destroy() which mutates the underlying map).
+     */
+    snapshot(): SessionState[];
+    /**
+     * Mark sessions whose single-mode binding (or gateway-pin) targets the
+     * named project as `cancelled`. The next tool call on a cancelled session
+     * returns SESSION_CANCELLED and then destroys the session. Multi-mode
+     * sessions are NOT cancelled here — use `pruneProjectFromWhitelist` for
+     * those. Returns the session IDs that were cancelled.
+     */
+    cancelByProject(projectName: string): string[];
+    /**
+     * Remove a project from multi-mode sessions' whitelist + effectiveRoles.
+     * Single-mode sessions are not touched (handled by `cancelByProject`).
+     * A multi-mode session whose whitelist becomes empty after pruning is
+     * marked cancelled — it has no remaining projects to route to.
+     * Returns { prunedSessions, cancelledSessions } lists.
+     */
+    pruneProjectFromWhitelist(projectName: string): {
+        prunedSessions: string[];
+        cancelledSessions: string[];
+    };
+    bindSingle(sessionId: string, projectName: string, opts?: BindOptions): Result<SessionState>;
+    bindMulti(sessionId: string, projectNames: string[], opts?: BindOptions): Result<SessionState>;
+    /**
+     * Compose the effective role for a (project, token?, requested?) tuple.
+     * Three-cap when a token is present (HTTP+registry mode); two-cap legacy
+     * behavior when token is undefined (stdio, synthetic, or any path that
+     * never populated state.token).
+     */
+    private composeEffective;
+}
+export declare function resolveSessionId(extra: unknown): string;
+export declare function __resetStdioSessionId(): void;
+//# sourceMappingURL=session.d.ts.map

package/dist/instance/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/instance/session.ts"],"names":[],"mappings":"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"}