@zenera/gym 1.1.40 → 1.1.42

package/dist/store.js

@@ -0,0 +1,253 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+const UPSERT = `
+    INSERT INTO records (collection, id, data, updated_at) VALUES (?, ?, ?, ?)
+    ON CONFLICT(collection, id) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at
+`;
+export class WorldStore {
+    path;
+    #db;
+    constructor(path) {
+        this.path = resolve(path);
+        mkdirSync(dirname(this.path), { recursive: true });
+        this.#db = new DatabaseSync(this.path);
+        this.#db.exec(`
+            PRAGMA busy_timeout = 10000;
+            PRAGMA journal_mode = WAL;
+            PRAGMA synchronous = NORMAL;
+            CREATE TABLE IF NOT EXISTS records (
+                collection TEXT NOT NULL,
+                id TEXT NOT NULL,
+                data TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                PRIMARY KEY (collection, id)
+            );
+            CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+        `);
+    }
+    collection(name) {
+        const db = this.#db;
+        const col = name.trim();
+        const parse = (text) => {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const all = () => db
+            .prepare('SELECT data FROM records WHERE collection = ? ORDER BY rowid')
+            .all(col)
+            .map((row) => parse(row.data))
+            .filter((v) => v !== undefined);
+        return {
+            name: col,
+            count: () => Number(db
+                .prepare('SELECT COUNT(*) AS n FROM records WHERE collection = ?')
+                .get(col).n),
+            all,
+            get: (id) => {
+                const row = db
+                    .prepare('SELECT data FROM records WHERE collection = ? AND id = ?')
+                    .get(col, String(id));
+                return row ? parse(row.data) : undefined;
+            },
+            has: (id) => db
+                .prepare('SELECT 1 FROM records WHERE collection = ? AND id = ?')
+                .get(col, String(id)) !== undefined,
+            find: (predicate) => all().filter(predicate),
+            put: (id, value) => {
+                db.prepare(UPSERT).run(col, String(id), JSON.stringify(value), new Date().toISOString());
+                return value;
+            },
+            putMany: (items) => {
+                const stmt = db.prepare(UPSERT);
+                const now = new Date().toISOString();
+                db.exec('BEGIN IMMEDIATE');
+                try {
+                    for (const item of items) {
+                        stmt.run(col, String(item.id), JSON.stringify(item.value), now);
+                    }
+                    db.exec('COMMIT');
+                }
+                catch (err) {
+                    db.exec('ROLLBACK');
+                    throw err;
+                }
+                return items.length;
+            },
+            delete: (id) => Number(db
+                .prepare('DELETE FROM records WHERE collection = ? AND id = ?')
+                .run(col, String(id)).changes) > 0,
+            clear: () => {
+                db.prepare('DELETE FROM records WHERE collection = ?').run(col);
+            },
+        };
+    }
+    collections() {
+        const rows = db(this).prepare('SELECT collection, COUNT(*) AS n FROM records GROUP BY collection ORDER BY collection');
+        return rows.all().map((row) => ({
+            name: row.collection,
+            count: Number(row.n),
+            sampleIds: db(this)
+                .prepare('SELECT id FROM records WHERE collection = ? ORDER BY rowid LIMIT 5')
+                .all(row.collection).map((r) => r.id),
+        }));
+    }
+    getMeta(key) {
+        const row = this.#db.prepare('SELECT value FROM meta WHERE key = ?').get(key);
+        return row ? JSON.parse(row.value) : undefined;
+    }
+    setMeta(key, value) {
+        this.#db
+            .prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value')
+            .run(key, JSON.stringify(value));
+    }
+    /**
+     * A consistent copy of the whole world, for judging a handler without
+     * letting its test traffic leak into what real requests will see.
+     */
+    snapshot(to) {
+        const target = resolve(to);
+        mkdirSync(dirname(target), { recursive: true });
+        this.#db.prepare('VACUUM INTO ?').run(target);
+        return target;
+    }
+    /**
+     * Takes a lease, or says someone else holds it. A lease is a row in `meta`
+     * claimed inside one immediate transaction, so two processes on the same
+     * file cannot both win; it lapses when its time is up or its process is
+     * gone, so a crash costs nobody a wait.
+     */
+    claim(key, owner, ttlMs) {
+        const name = `lease:${key}`;
+        const now = Date.now();
+        this.#db.exec('BEGIN IMMEDIATE');
+        try {
+            const row = this.#db.prepare('SELECT value FROM meta WHERE key = ?').get(name);
+            const held = row ? JSON.parse(row.value) : undefined;
+            if (held && held.owner !== owner && held.until > now && alive(held.owner)) {
+                this.#db.exec('COMMIT');
+                return false;
+            }
+            this.#db
+                .prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value')
+                .run(name, JSON.stringify({ owner, until: now + ttlMs }));
+            this.#db.exec('COMMIT');
+            return true;
+        }
+        catch (err) {
+            this.#db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+    /** Gives a lease back, if it is still this owner's. */
+    release(key, owner) {
+        const name = `lease:${key}`;
+        const row = this.#db.prepare('SELECT value FROM meta WHERE key = ?').get(name);
+        if (row && JSON.parse(row.value).owner === owner) {
+            this.#db.prepare('DELETE FROM meta WHERE key = ?').run(name);
+        }
+    }
+    /** Throws away every entity, keeping the file and its schema. */
+    reset() {
+        this.#db.exec('DELETE FROM records; DELETE FROM meta;');
+    }
+    close() {
+        try {
+            this.#db.close();
+        }
+        catch {
+            // already closed
+        }
+    }
+    /** @internal */
+    get raw() {
+        return this.#db;
+    }
+}
+const db = (store) => store.raw;
+/** A lease owner `<pid>:…` whose process still runs; anything else is taken as alive. */
+function alive(owner) {
+    const pid = Number(owner.split(':')[0]);
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return true;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** A lease owner for this process. */
+export const leaseOwner = () => `${process.pid}:${Math.random().toString(36).slice(2, 10)}`;
+/** A world named rather than given as a path: letters, digits, `.`, `_`, `-`. */
+const WORLD_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Where the world lives. `--world` wins: a name is a file under
+ * `<root>/worlds`, anything that looks like a path is that path. Otherwise the
+ * story names its own world, keyed by what the story says, so two processes
+ * handed the same story share one world without being told to; with neither,
+ * there is one default world.
+ */
+export function worldPath(opts) {
+    const named = opts.world?.trim();
+    if (named) {
+        if (/[\\/]/.test(named) || /\.(sqlite|db)$/i.test(named)) {
+            return resolve(opts.cwd, named);
+        }
+        if (!WORLD_NAME.test(named)) {
+            throw new Error(`"${named}" is not a world name: use letters, digits, ".", "_" and "-", or a path`);
+        }
+        return join(worldsDir(opts.root), `${named}.sqlite`);
+    }
+    const name = opts.storyDigest ? `story-${opts.storyDigest.slice(0, 16)}` : 'default';
+    return join(worldsDir(opts.root), `${name}.sqlite`);
+}
+export const worldsDir = (root) => join(root, 'worlds');
+/** Every world under `<root>/worlds`, most recently used first. */
+export function listWorlds(root) {
+    const dir = worldsDir(root);
+    let names;
+    try {
+        names = readdirSync(dir).filter((n) => n.endsWith('.sqlite'));
+    }
+    catch {
+        return [];
+    }
+    return names
+        .map((file) => {
+        const path = join(dir, file);
+        const info = statSync(path);
+        let collections = [];
+        try {
+            const store = new WorldStore(path);
+            collections = store.collections();
+            store.close();
+        }
+        catch {
+            // unreadable: listed, with nothing in it
+        }
+        return {
+            name: file.replace(/\.sqlite$/, ''),
+            path,
+            bytes: info.size,
+            usedAt: info.mtime,
+            collections,
+        };
+    })
+        .sort((a, b) => b.usedAt.getTime() - a.usedAt.getTime());
+}
+/** Deletes a world and the journal files SQLite keeps beside it. */
+export function removeWorld(path) {
+    for (const suffix of ['', '-wal', '-shm']) {
+        rmSync(`${path}${suffix}`, { force: true });
+    }
+}
+export const digest = (text) => createHash('sha256').update(text).digest('hex').slice(0, 16);
+//# sourceMappingURL=store.js.map

package/dist/synth.d.ts

@@ -0,0 +1,42 @@
+import { type Model } from '@zenera/neo';
+import type { Bindings } from './bindings.ts';
+import type { SynthesizeHook } from './box.ts';
+import type { Catalog } from './catalog.ts';
+import { WorldStore } from './store.ts';
+import type { Knowledge } from './knowledge.ts';
+export interface WorldEvent {
+    collection: string;
+    made: number;
+    /** the agent did not deliver and sampled records stood in */
+    fallback?: string;
+    /** records of other types made along the way, because these refer to them */
+    dependents?: number;
+    /** references in what was made that point at nothing in the world */
+    dangling?: string[];
+    report?: string;
+    durationMs: number;
+}
+export interface WorldOptions {
+    model: Model;
+    knowledge: Knowledge;
+    catalog: Catalog;
+    /** where each type lives; the world agent may place a type nobody has used yet */
+    bindings: Bindings;
+    /** the live world */
+    store: WorldStore;
+    reportDir?: string;
+    onMade?: (event: WorldEvent) => void;
+}
+export declare class World {
+    #private;
+    readonly store: WorldStore;
+    /** what the agents know: the story, and the docs with the tools that read them */
+    readonly knowledge: Knowledge;
+    constructor(opts: WorldOptions);
+    /** Given to the box: every request a handler makes for content lands here. */
+    readonly synthesize: SynthesizeHook;
+    /** Forgets a world that was only borrowed, such as a judging snapshot. */
+    release(db: string): void;
+    close(): void;
+}
+//# sourceMappingURL=synth.d.ts.map