@struktoai/mirage-node 0.0.5 → 0.0.7-alpha.1

package/dist/workspace/record/disk.js

@@ -0,0 +1,229 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { generationOf } from '@struktoai/mirage-core/workspace/record/types';
+// A .lock older than this is presumed abandoned by a crashed writer and
+// reclaimed (loudly). Live CAS critical sections are milliseconds.
+const LOCK_STALE_SECONDS = 10;
+const LOCK_RETRY_SLEEP_MS = 5;
+const LOCK_RETRY_LIMIT = 2000;
+let tmpCounter = 0;
+// Match Python's urllib quote(safe=""): percent-encode everything
+// outside the unreserved set, so both runtimes produce byte-identical
+// filenames over one shared state directory.
+function quoteName(name) {
+    return encodeURIComponent(name).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function isMissing(e) {
+    return e.code === 'ENOENT';
+}
+/**
+ * One JSON-record-per-file client with lockfile CAS.
+ *
+ * The disk twin of `S3RecordClient`: a record is one file at
+ * `{root}/{prefix}{name}.json`, written atomically (tmp then rename(2))
+ * so readers never see a torn record. The conditional write serializes
+ * on a `{record}.lock` created with O_CREAT|O_EXCL, so compare and
+ * write hit the same stored version. Record names are percent-encoded
+ * into filenames, so any id is safe. Mirrors the Python
+ * DiskRecordClient byte-for-byte on disk.
+ */
+export class DiskRecordClient {
+    dir;
+    constructor(root, prefix) {
+        this.dir = path.join(root, prefix);
+    }
+    recordPath(name) {
+        return path.join(this.dir, `${quoteName(name)}.json`);
+    }
+    // The token slot mirrors the S3 client's ETag but stays empty: disk
+    // CAS anchors on the lockfile, not on a version token.
+    async get(name) {
+        let body;
+        try {
+            body = await readFile(this.recordPath(name));
+        }
+        catch (e) {
+            if (isMissing(e))
+                return [null, ''];
+            throw e;
+        }
+        return [JSON.parse(body.toString()), ''];
+    }
+    async put(name, fields) {
+        await mkdir(this.dir, { recursive: true });
+        await this.writeRecord(this.recordPath(name), fields);
+    }
+    /**
+     * Write one record iff its stored generation matches.
+     *
+     * Take the record's lockfile, re-read under the lock, check the
+     * generation, then tmp-write + rename. Losing the lock race or the
+     * generation check resolves false; the caller adopts and retries.
+     */
+    async casPut(name, fields, expectedGeneration) {
+        await mkdir(this.dir, { recursive: true });
+        const target = this.recordPath(name);
+        const lockPath = `${target}.lock`;
+        let fh = await this.acquireLock(lockPath);
+        if (fh === null) {
+            if (!(await this.reclaimStaleLock(lockPath)))
+                return false;
+            fh = await this.acquireLock(lockPath);
+            if (fh === null)
+                return false;
+        }
+        try {
+            const [stored] = await this.get(name);
+            if (generationOf(stored) !== expectedGeneration)
+                return false;
+            await this.writeRecord(target, fields);
+            return true;
+        }
+        finally {
+            await this.releaseLock(fh, lockPath);
+        }
+    }
+    async listNames() {
+        let entries;
+        try {
+            entries = await readdir(this.dir);
+        }
+        catch (e) {
+            if (isMissing(e))
+                return [];
+            throw e;
+        }
+        return entries
+            .filter((n) => n.endsWith('.json'))
+            .map((n) => decodeURIComponent(n.slice(0, -'.json'.length)));
+    }
+    async loadAll() {
+        const names = await this.listNames();
+        const records = await Promise.all(names.map((name) => this.get(name)));
+        const out = new Map();
+        for (let i = 0; i < names.length; i++) {
+            const name = names[i];
+            const fields = records[i]?.[0];
+            if (name !== undefined && fields != null)
+                out.set(name, fields);
+        }
+        return out;
+    }
+    async delete(names) {
+        for (const name of names) {
+            try {
+                await unlink(this.recordPath(name));
+            }
+            catch (e) {
+                // Delete promises absence; already-absent is success.
+                if (!isMissing(e))
+                    throw e;
+            }
+        }
+    }
+    async clear() {
+        await this.delete(await this.listNames());
+    }
+    async close() {
+        // Nothing held open between calls.
+    }
+    /**
+     * Block until this record's lockfile is held; handle to release.
+     *
+     * For callers doing a read-modify-write that is not generation-CAS
+     * (e.g. the single-file namespace plane); spins past contention and
+     * reclaims stale locks, throwing only if a live writer holds the
+     * lock for the whole retry budget (~10s).
+     */
+    async lock(name) {
+        await mkdir(this.dir, { recursive: true });
+        const lockPath = `${this.recordPath(name)}.lock`;
+        for (let i = 0; i < LOCK_RETRY_LIMIT; i++) {
+            const fh = await this.acquireLock(lockPath);
+            if (fh !== null)
+                return fh;
+            if (await this.reclaimStaleLock(lockPath))
+                continue;
+            await new Promise((r) => setTimeout(r, LOCK_RETRY_SLEEP_MS));
+        }
+        throw new Error(`could not acquire lock ${lockPath}`);
+    }
+    async unlock(name, fh) {
+        await this.releaseLock(fh, `${this.recordPath(name)}.lock`);
+    }
+    // O_CREAT|O_EXCL ('wx'): filesystem-atomic mutex, the git protocol.
+    // Local filesystems only (O_EXCL is unreliable on ancient NFS, the
+    // same caveat git ships with).
+    async acquireLock(lockPath) {
+        let fh;
+        try {
+            fh = await open(lockPath, 'wx');
+        }
+        catch (e) {
+            if (e.code === 'EEXIST')
+                return null;
+            throw e;
+        }
+        await fh.write(String(process.pid));
+        return fh;
+    }
+    // True when the lock is gone or was stale and removed; false when a
+    // live writer still holds it.
+    async reclaimStaleLock(lockPath) {
+        let mtimeMs;
+        try {
+            mtimeMs = (await stat(lockPath)).mtimeMs;
+        }
+        catch (e) {
+            if (isMissing(e))
+                return true;
+            throw e;
+        }
+        const age = (Date.now() - mtimeMs) / 1000;
+        if (age <= LOCK_STALE_SECONDS)
+            return false;
+        console.warn(`mirage: reclaiming stale lock ${lockPath} (age ${age.toFixed(1)}s)`);
+        try {
+            await unlink(lockPath);
+        }
+        catch (e) {
+            // The holder released it between the stat and the unlink; the
+            // lock is gone either way, which is all this method promises.
+            if (!isMissing(e))
+                throw e;
+        }
+        return true;
+    }
+    async releaseLock(fh, lockPath) {
+        await fh.close();
+        try {
+            await unlink(lockPath);
+        }
+        catch (e) {
+            // Only reachable when another writer reclaimed this lock as
+            // stale; the record write already landed, nothing to undo.
+            if (!isMissing(e))
+                throw e;
+            console.warn(`mirage: lock ${lockPath} vanished before release (reclaimed?)`);
+        }
+    }
+    async writeRecord(target, fields) {
+        const tmp = `${target}.${String(process.pid)}.${String(tmpCounter++)}.tmp`;
+        await writeFile(tmp, JSON.stringify(fields));
+        await rename(tmp, target);
+    }
+}
+//# sourceMappingURL=disk.js.map

package/dist/workspace/record/disk.js.map

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

package/dist/workspace/session/disk.d.ts

@@ -0,0 +1,22 @@
+import { SessionStore } from '@struktoai/mirage-core/workspace/session/store';
+import type { SessionFields } from '@struktoai/mirage-core/workspace/session/store';
+/**
+ * SessionStore backed by per-session files under one directory.
+ *
+ * One file per session at `{root}/sessions/{session_id}.json`, lockfile
+ * CAS per record, so multiple local processes share one session table
+ * with the same generation contract as the Redis Lua script, with zero
+ * infrastructure. Mirrors the Python DiskSessionStore.
+ */
+export declare class DiskSessionStore extends SessionStore {
+    private readonly records;
+    constructor(root: string);
+    load(): Promise<Map<string, SessionFields>>;
+    set(sessionId: string, fields: SessionFields): Promise<void>;
+    casSet(sessionId: string, fields: SessionFields, expectedGeneration: number): Promise<boolean>;
+    delete(sessionIds: readonly string[]): Promise<void>;
+    replaceAll(entries: Map<string, SessionFields>): Promise<void>;
+    clear(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=disk.d.ts.map

package/dist/workspace/session/disk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk.d.ts","sourceRoot":"","sources":["../../../src/workspace/session/disk.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAA;AAInF;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;gBAE9B,IAAI,EAAE,MAAM;IAKlB,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAI3C,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa,EACrB,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,OAAO,CAAC;IAIb,MAAM,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/workspace/session/disk.js

@@ -0,0 +1,54 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { SessionStore } from '@struktoai/mirage-core/workspace/session/store';
+import { DiskRecordClient } from "../record/disk.js";
+/**
+ * SessionStore backed by per-session files under one directory.
+ *
+ * One file per session at `{root}/sessions/{session_id}.json`, lockfile
+ * CAS per record, so multiple local processes share one session table
+ * with the same generation contract as the Redis Lua script, with zero
+ * infrastructure. Mirrors the Python DiskSessionStore.
+ */
+export class DiskSessionStore extends SessionStore {
+    records;
+    constructor(root) {
+        super();
+        this.records = new DiskRecordClient(root, 'sessions/');
+    }
+    async load() {
+        return await this.records.loadAll();
+    }
+    async set(sessionId, fields) {
+        await this.records.put(sessionId, fields);
+    }
+    async casSet(sessionId, fields, expectedGeneration) {
+        return await this.records.casPut(sessionId, fields, expectedGeneration);
+    }
+    async delete(sessionIds) {
+        await this.records.delete(sessionIds);
+    }
+    async replaceAll(entries) {
+        const stale = (await this.records.listNames()).filter((n) => !entries.has(n));
+        await this.records.delete(stale);
+        await Promise.all([...entries].map(([sid, fields]) => this.records.put(sid, fields)));
+    }
+    async clear() {
+        await this.records.clear();
+    }
+    async close() {
+        await this.records.close();
+    }
+}
+//# sourceMappingURL=disk.js.map

package/dist/workspace/session/disk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk.js","sourceRoot":"","sources":["../../../src/workspace/session/disk.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAA;AAG7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEpD;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAC/B,OAAO,CAAkB;IAE1C,YAAY,IAAY;QACtB,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,OAAO,GAAG,IAAI,gBAAgB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;IACxD,CAAC;IAED,KAAK,CAAC,IAAI;QACR,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAA;IACrC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,SAAiB,EAAE,MAAqB;QAChD,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IAC3C,CAAC;IAED,KAAK,CAAC,MAAM,CACV,SAAiB,EACjB,MAAqB,EACrB,kBAA0B;QAE1B,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAA;IACzE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,UAA6B;QACxC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IACvC,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,OAAmC;QAClD,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QAC7E,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAChC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IACvF,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IAC5B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IAC5B,CAAC;CACF"}

package/dist/workspace/session/redis.d.ts

@@ -0,0 +1,32 @@
+import { SessionStore } from '@struktoai/mirage-core/workspace/session/store';
+import type { SessionFields } from '@struktoai/mirage-core/workspace/session/store';
+export declare const CAS_SCRIPT: string;
+export interface RedisSessionStoreOptions {
+    url?: string;
+    keyPrefix?: string;
+}
+/**
+ * SessionStore backed by one Redis hash (session id -> JSON fields).
+ *
+ * Sessions and the mount grants they carry survive restarts and are
+ * visible to every workspace pointed at the same key prefix — the seam
+ * that lets one process create a session and another (a kernel tier, a
+ * sibling daemon) bind a mountpoint to it. Writes are single-command
+ * (HSET/HDEL) so mutations stay one round trip. Mirrors the Python
+ * RedisSessionStore.
+ */
+export declare class RedisSessionStore extends SessionStore {
+    readonly url: string;
+    private readonly key;
+    private clientPromise;
+    constructor(options?: RedisSessionStoreOptions);
+    private client;
+    casSet(sessionId: string, fields: SessionFields, expectedGeneration: number): Promise<boolean>;
+    load(): Promise<Map<string, SessionFields>>;
+    set(sessionId: string, fields: SessionFields): Promise<void>;
+    delete(sessionIds: readonly string[]): Promise<void>;
+    replaceAll(entries: Map<string, SessionFields>): Promise<void>;
+    clear(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=redis.d.ts.map

package/dist/workspace/session/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../../src/workspace/session/redis.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAA;AAMnF,eAAO,MAAM,UAAU,QAA8D,CAAA;AAErF,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,aAAa,CAAwC;gBAEjD,OAAO,GAAE,wBAA6B;YAOpC,MAAM;IAqBd,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa,EACrB,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,OAAO,CAAC;IASb,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAU3C,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D,MAAM,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpD,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAU7B"}

package/dist/workspace/session/redis.js

@@ -0,0 +1,106 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { readFileSync } from 'node:fs';
+import { SessionStore } from '@struktoai/mirage-core/workspace/session/store';
+import { loadOptionalPeer } from "../../optional_peer.js";
+// Shipped next to this module in src and copied beside the bundle in
+// dist (scripts/copy-assets.mjs); byte-identical to the Python cas.lua. Generic
+// hash-field CAS, shared with the workspace meta record.
+export const CAS_SCRIPT = readFileSync(new URL('./cas.lua', import.meta.url), 'utf8');
+/**
+ * SessionStore backed by one Redis hash (session id -> JSON fields).
+ *
+ * Sessions and the mount grants they carry survive restarts and are
+ * visible to every workspace pointed at the same key prefix — the seam
+ * that lets one process create a session and another (a kernel tier, a
+ * sibling daemon) bind a mountpoint to it. Writes are single-command
+ * (HSET/HDEL) so mutations stay one round trip. Mirrors the Python
+ * RedisSessionStore.
+ */
+export class RedisSessionStore extends SessionStore {
+    url;
+    key;
+    clientPromise = null;
+    constructor(options = {}) {
+        super();
+        this.url = options.url ?? 'redis://localhost:6379/0';
+        const prefix = options.keyPrefix ?? 'mirage:session:';
+        this.key = `${prefix}sessions`;
+    }
+    async client() {
+        this.clientPromise ??= (async () => {
+            const mod = await loadOptionalPeer(() => import('redis'), { feature: 'RedisSessionStore', packageName: 'redis' });
+            const c = mod.createClient({
+                url: this.url,
+                socket: { reconnectStrategy: false },
+            });
+            await c.connect();
+            return c;
+        })();
+        return this.clientPromise;
+    }
+    // One atomic server-side compare-and-set: Lua reads the stored
+    // record's generation and writes only on a match.
+    async casSet(sessionId, fields, expectedGeneration) {
+        const c = await this.client();
+        const result = await c.eval(CAS_SCRIPT, {
+            keys: [this.key],
+            arguments: [sessionId, JSON.stringify(fields), String(expectedGeneration)],
+        });
+        return result === 1;
+    }
+    async load() {
+        const c = await this.client();
+        const raw = await c.hGetAll(this.key);
+        const out = new Map();
+        for (const [sid, value] of Object.entries(raw)) {
+            out.set(sid, JSON.parse(value));
+        }
+        return out;
+    }
+    async set(sessionId, fields) {
+        const c = await this.client();
+        await c.hSet(this.key, sessionId, JSON.stringify(fields));
+    }
+    async delete(sessionIds) {
+        if (sessionIds.length === 0)
+            return;
+        const c = await this.client();
+        await c.hDel(this.key, [...sessionIds]);
+    }
+    async replaceAll(entries) {
+        const c = await this.client();
+        const multi = c.multi().del(this.key);
+        for (const [sid, fields] of entries) {
+            multi.hSet(this.key, sid, JSON.stringify(fields));
+        }
+        await multi.exec();
+    }
+    async clear() {
+        const c = await this.client();
+        await c.del(this.key);
+    }
+    async close() {
+        // Idempotent: the workspace closes the plane store it consumed and the
+        // owning WorkspaceStateStore closes every plane it built; the second
+        // close must be a no-op, not a crash on an already-quit client.
+        if (this.clientPromise === null)
+            return;
+        const pending = this.clientPromise;
+        this.clientPromise = null;
+        const c = await pending;
+        await c.quit();
+    }
+}
+//# sourceMappingURL=redis.js.map

package/dist/workspace/session/redis.js.map

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

package/dist/workspace/store/disk.d.ts

@@ -0,0 +1,46 @@
+import type { ObserverStore } from '@struktoai/mirage-core/observe/store';
+import type { NamespaceStore } from '@struktoai/mirage-core/workspace/mount/namespace/store';
+import type { SessionStore } from '@struktoai/mirage-core/workspace/session/store';
+import { WorkspaceStateStore } from '@struktoai/mirage-core/workspace/store/base';
+import type { WorkspaceFields, WorkspaceStateStoreOverrides } from '@struktoai/mirage-core/workspace/store/base';
+export declare const DEFAULT_STATE_ROOT = "~/.mirage/state";
+export interface DiskWorkspaceStateStoreOptions extends WorkspaceStateStoreOverrides {
+    root?: string;
+}
+/**
+ * WorkspaceStateStore backed by a directory tree.
+ *
+ * Each workspace is one self-contained directory (delete a workspace
+ * by removing its folder):
+ *
+ * - `{root}/workspaces/{ws}/workspace.json` — metadata record
+ * - `{root}/workspaces/{ws}/sessions/{sid}.json` — session table
+ * - `{root}/workspaces/{ws}/namespace.json` — nodes + user, one JSON
+ * - `{root}/workspaces/{ws}/history/<day>/<sid>.jsonl` — history
+ *
+ * The layout mirrors the S3 store file-for-object; mutable records get
+ * the same generation-CAS contract via the lockfile protocol
+ * (O_CREAT|O_EXCL mutex, tmp write, rename(2)), so multiple local
+ * processes share one workspace with zero infrastructure: a CLI-created
+ * workspace survives restart like `git init`. Local filesystems only;
+ * anything cross-machine belongs on redis or s3. Mirrors the Python
+ * DiskWorkspaceStateStore byte-for-byte on disk.
+ */
+export declare class DiskWorkspaceStateStore extends WorkspaceStateStore {
+    private readonly root;
+    private readonly meta;
+    private readonly namespaces;
+    private readonly observers;
+    private readonly sessionTables;
+    constructor(options?: DiskWorkspaceStateStoreOptions);
+    private wsRoot;
+    private metaClient;
+    protected makeNamespace(workspaceId: string): NamespaceStore;
+    protected makeObserver(workspaceId: string): ObserverStore;
+    protected makeSessions(workspaceId: string): SessionStore;
+    protected readMeta(workspaceId: string): Promise<WorkspaceFields | null>;
+    protected writeMeta(workspaceId: string, fields: WorkspaceFields): Promise<void>;
+    protected casWriteMeta(workspaceId: string, fields: WorkspaceFields, expectedGeneration: number): Promise<boolean>;
+    protected closeSelf(): Promise<void>;
+}
+//# sourceMappingURL=disk.d.ts.map

package/dist/workspace/store/disk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk.d.ts","sourceRoot":"","sources":["../../../src/workspace/store/disk.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAA;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wDAAwD,CAAA;AAC5F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAA;AAClF,OAAO,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAA;AACjF,OAAO,KAAK,EACV,eAAe,EACf,4BAA4B,EAC7B,MAAM,6CAA6C,CAAA;AAMpD,eAAO,MAAM,kBAAkB,oBAAoB,CAAA;AAgBnD,MAAM,WAAW,8BAA+B,SAAQ,4BAA4B;IAClF,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,uBAAwB,SAAQ,mBAAmB;IAC9D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsC;IAC3D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwC;IACnE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IACjE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsC;gBAExD,OAAO,GAAE,8BAAmC;IAMxD,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,UAAU;IASlB,SAAS,CAAC,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc;IAS5D,SAAS,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa;IAS1D,SAAS,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY;cASzC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;cAK9D,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;cAItE,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,eAAe,EACvB,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,OAAO,CAAC;cAIH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAM3C"}

package/dist/workspace/store/disk.js

@@ -0,0 +1,119 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { WorkspaceStateStore } from '@struktoai/mirage-core/workspace/store/base';
+import { DiskObserverStore } from "../../observe/disk_store.js";
+import { DiskNamespaceStore } from "../namespace/disk.js";
+import { DiskRecordClient } from "../record/disk.js";
+import { DiskSessionStore } from "../session/disk.js";
+export const DEFAULT_STATE_ROOT = '~/.mirage/state';
+function expandHome(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/'))
+        return path.join(homedir(), p.slice(2));
+    return p;
+}
+// Match Python's urllib quote(safe="") for the workspace path segment.
+function quoteSegment(name) {
+    return encodeURIComponent(name).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/**
+ * WorkspaceStateStore backed by a directory tree.
+ *
+ * Each workspace is one self-contained directory (delete a workspace
+ * by removing its folder):
+ *
+ * - `{root}/workspaces/{ws}/workspace.json` — metadata record
+ * - `{root}/workspaces/{ws}/sessions/{sid}.json` — session table
+ * - `{root}/workspaces/{ws}/namespace.json` — nodes + user, one JSON
+ * - `{root}/workspaces/{ws}/history/<day>/<sid>.jsonl` — history
+ *
+ * The layout mirrors the S3 store file-for-object; mutable records get
+ * the same generation-CAS contract via the lockfile protocol
+ * (O_CREAT|O_EXCL mutex, tmp write, rename(2)), so multiple local
+ * processes share one workspace with zero infrastructure: a CLI-created
+ * workspace survives restart like `git init`. Local filesystems only;
+ * anything cross-machine belongs on redis or s3. Mirrors the Python
+ * DiskWorkspaceStateStore byte-for-byte on disk.
+ */
+export class DiskWorkspaceStateStore extends WorkspaceStateStore {
+    root;
+    meta = new Map();
+    namespaces = new Map();
+    observers = new Map();
+    sessionTables = new Map();
+    constructor(options = {}) {
+        const { root, ...overrides } = options;
+        super(overrides);
+        this.root = expandHome(root ?? DEFAULT_STATE_ROOT);
+    }
+    wsRoot(workspaceId) {
+        return path.join(this.root, 'workspaces', quoteSegment(workspaceId));
+    }
+    metaClient(workspaceId) {
+        let client = this.meta.get(workspaceId);
+        if (client === undefined) {
+            client = new DiskRecordClient(this.wsRoot(workspaceId), '');
+            this.meta.set(workspaceId, client);
+        }
+        return client;
+    }
+    makeNamespace(workspaceId) {
+        let ns = this.namespaces.get(workspaceId);
+        if (ns === undefined) {
+            ns = new DiskNamespaceStore(this.wsRoot(workspaceId));
+            this.namespaces.set(workspaceId, ns);
+        }
+        return ns;
+    }
+    makeObserver(workspaceId) {
+        let ob = this.observers.get(workspaceId);
+        if (ob === undefined) {
+            ob = new DiskObserverStore(path.join(this.wsRoot(workspaceId), 'history'));
+            this.observers.set(workspaceId, ob);
+        }
+        return ob;
+    }
+    makeSessions(workspaceId) {
+        let table = this.sessionTables.get(workspaceId);
+        if (table === undefined) {
+            table = new DiskSessionStore(this.wsRoot(workspaceId));
+            this.sessionTables.set(workspaceId, table);
+        }
+        return table;
+    }
+    async readMeta(workspaceId) {
+        const [fields] = await this.metaClient(workspaceId).get('workspace');
+        return fields;
+    }
+    async writeMeta(workspaceId, fields) {
+        await this.metaClient(workspaceId).put('workspace', fields);
+    }
+    async casWriteMeta(workspaceId, fields, expectedGeneration) {
+        return await this.metaClient(workspaceId).casPut('workspace', fields, expectedGeneration);
+    }
+    async closeSelf() {
+        for (const ns of this.namespaces.values())
+            await ns.close();
+        for (const ob of this.observers.values())
+            await ob.close();
+        for (const table of this.sessionTables.values())
+            await table.close();
+        for (const client of this.meta.values())
+            await client.close();
+    }
+}
+//# sourceMappingURL=disk.js.map