@sema-agent/core 7.48.0 → 7.49.0

package/dist/stores/file/strategy-store.d.ts

@@ -1,97 +0,0 @@
-import { type StoredStrategy, type StrategyStore, type StrategyStoreIncident } from "../../core/strategy-store.js";
-/**
- * File-backed {@link StrategyStore} — the persistence twin of `InMemoryStrategyStore`, so the teacher
- * mode's cross-session reuse premise actually holds on a local (TOC) deployment where every session is
- * a fresh process (an in-memory strategy repository there re-learns everything, every time).
- *
- * DESIGN STANCE — this is a **cache, not an authority store**: every entry is regenerable (worst case:
- * ask the teacher again), so losing one never loses correctness. It therefore deliberately skips the
- * journal/shadow armor of the memory file backend and does NOT fsync-harden beyond the shared
- * atomic-write primitive, does NOT take a cross-process lock, and accepts a narrow multi-process race
- * on save-side dedup (two processes can each write one copy of the same normalized entry — the read
- * side dedups, and a lost max-confidence merge is cache-grade). What it does NOT relax: scope
- * isolation and loud-refusal discipline, which are held to the same standard as the durable stores.
- *
- * Layout: `<root>/<scopeDir>/<id>.json`, one strategy per file, whole-file atomic replace on write.
- * `scopeDir = slug(scope) + "-" + sha256(scope).slice(0,24)` — the slug is a strict `[a-z0-9-]`
- * whitelist purely for readability; IDENTITY lives in the 96-bit hash, so no scope value, however
- * adversarial, can traverse out of the root or collide another scope's directory. Ids are gated to
- * `[A-Za-z0-9_-]{1,64}` at save (the escalation loop mints UUIDs; the interface is public, so a
- * hand-rolled id must not be able to name a path).
- *
- * `scope` is a NAMESPACE, not an authorization boundary — the store cannot authenticate its caller;
- * whoever holds the instance can address any scope (same posture as the memory store). Authorization
- * is the host's obligation.
- */
-export interface FileStrategyStoreOptions {
-    /** Directory to keep strategies under (created `0o700` if absent; a non-directory or unwritable
-     *  path is refused loudly at construction — a store that cannot persist must not pretend to). */
-    root: string;
-    /** Per-scope capacity cap (entries), evicting the lowest-scoring on overflow. Default 100. */
-    maxPerScope?: number;
-    /**
-     * Disclosure sink for contained store incidents (a corrupt entry quarantined, an eviction that
-     * failed after a successful save, a degraded read). Absent ⇒ `console.warn`, once per op kind —
-     * a contained fault must be loud somewhere, but must never flood.
-     */
-    onIncident?: (i: StrategyStoreIncident) => void;
-}
-export declare class FileStrategyStore implements StrategyStore {
-    private readonly root;
-    private readonly maxPerScope;
-    private readonly onIncident?;
-    /** Ops that already warned on the absent-sink fallback (bounded disclosure — never flood). */
-    private readonly warnedOps;
-    /** Isolation scope for the host incident sink (sync throw AND async rejection contained). */
-    private readonly sinkNotifier;
-    /** Scope dirs whose stale temps this instance already swept (once per scope per instance). */
-    private readonly sweptTemps;
-    constructor(opts: FileStrategyStoreOptions);
-    /** `slug(scope)-sha256(scope)[0..24]` — slug is readability only; the hash is the injective key. */
-    private scopeDirName;
-    private scopeDirPath;
-    /** The scope dir must be a REAL directory — a symlink here means the store's namespace was tampered
-     *  with (a link could point retrieval at another scope's data, or writes out of the root). The
-     *  check-then-use window against a same-uid untrusted local process is out of the threat model: such a
-     *  process already holds the same rights as the store itself. */
-    private assertScopeDirSafe;
-    private incident;
-    /** Sweep crashed writers' stale temps (once per scope per instance). Fresh temps are left alone —
-     *  they may belong to a live concurrent writer. */
-    private sweepStaleTemps;
-    /** Load every VALID entry of a scope dir. Corrupt files are quarantined (`.bad` rename) with one
-     *  disclosure; entries that violate the read-side invariants (foreign scope / id≠filename) are
-     *  skipped with disclosure but NOT quarantined (a copied-in file may be someone's valid data);
-     *  normalized duplicates collapse to the best-scoring copy. */
-    private loadScope;
-    /** Rename a corrupt file to `<name>.bad` — one disclosure now, zero parse cost on every later read
-     *  (the suffix no longer matches the entry-file grammar). Never faults the calling operation. */
-    private quarantine;
-    /** Serialize + write one entry, refusing a record whose SERIALIZED form exceeds the read bound.
-     *  The field caps bound RAW string bytes, but JSON escaping expands control characters up to 6x —
-     *  without this door a save could succeed and then self-quarantine on the very next read (the
-     *  worst possible shape: an accepted write the store itself later refuses to serve). */
-    private writeEntry;
-    save(s: StoredStrategy): void;
-    private evict;
-    find(scope: string, query: string, limit: number): StoredStrategy[];
-    /** Bounded candidate view for the RETRIEVAL-adjacent paths (find/hasStrategy/save): an externally
-     *  inflated directory must not make a hot operation unbounded. MAINTENANCE passes Infinity — see
-     *  {@link prune}. */
-    private retrievalReadCap;
-    /**
-     * Trims to `maxSize` over an UNCAPPED enumeration: prune is the reconciliation verb, so it must see
-     * every entry file — under the bounded retrieval view, a capacity SHRINK across restarts (or
-     * `maxPerScope: 0`) left files beyond the window untouched, reporting success while the "removed"
-     * strategies sat on disk ready to resurrect under a later, larger capacity. Host-invoked
-     * maintenance accepts the O(all files) cost the retrieval path refuses.
-     */
-    prune(scope: string, maxSize: number): void;
-    /** Uncapped for the same reason as {@link prune}: this face feeds the seed capacity door, and an
-     *  under-count there turns "refuse what cannot fit" into silent eviction of fresh seeds. */
-    scopeUsage(scope: string): {
-        used: number;
-        capacity: number;
-    };
-    hasStrategy(scope: string, entry: Pick<StoredStrategy, "problem" | "strategy">): boolean;
-}

package/dist/stores/file/strategy-store.js

@@ -1,341 +0,0 @@
-import { accessSync, constants as FS, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { createHash } from "node:crypto";
-import { atomicWriteFile } from "./fs-atomic.js";
-import { createSafeNotifier, observeThenableRejection } from "../../core/safe-notify.js";
-import { thrownText } from "../../core/thrown-value.js";
-import { MAX_STRATEGY_INJECTION_TOTAL_BYTES, MAX_STRATEGY_TEXT_BYTES, compileStrategyQuery, resolveCapacityCap, resolveFindLimit, scoreStoredStrategy, storedStrategyShapeIssue, strategyDedupKey, validateStrategyForWrite, } from "../../core/strategy-store.js";
-function configRefusal(message, code) {
-    const e = new Error(message);
-    e.code = code;
-    return e;
-}
-const SCOPE_SLUG_MAX = 40;
-const READ_FILE_CAP_FACTOR = 4;
-const STALE_TEMP_MS = 60 * 60 * 1000;
-const MAX_ENTRY_FILE_BYTES = 65536;
-const FILE_RE = /^([A-Za-z0-9_-]{1,64})\.json$/;
-export class FileStrategyStore {
-    root;
-    maxPerScope;
-    onIncident;
-    warnedOps = new Set();
-    sinkNotifier = createSafeNotifier();
-    sweptTemps = new Set();
-    constructor(opts) {
-        this.maxPerScope = resolveCapacityCap("maxPerScope", opts.maxPerScope ?? 100);
-        this.onIncident = opts.onIncident;
-        const root = opts.root;
-        if (typeof root !== "string" || root.length === 0) {
-            throw configRefusal("FileStrategyStore: root must be a non-empty path", "config.strategy_root_invalid");
-        }
-        try {
-            mkdirSync(root, { recursive: true, mode: 0o700 });
-        }
-        catch (err) {
-            throw configRefusal(`FileStrategyStore: cannot create root ${root}: ${thrownText(err)}`, "config.strategy_root_invalid");
-        }
-        let st;
-        try {
-            st = statSync(root);
-        }
-        catch (err) {
-            throw configRefusal(`FileStrategyStore: cannot stat root ${root}: ${thrownText(err)}`, "config.strategy_root_invalid");
-        }
-        if (!st.isDirectory()) {
-            throw configRefusal(`FileStrategyStore: root ${root} exists and is not a directory`, "config.strategy_root_invalid");
-        }
-        try {
-            accessSync(root, FS.W_OK);
-        }
-        catch {
-            throw configRefusal(`FileStrategyStore: root ${root} is not writable`, "config.strategy_root_invalid");
-        }
-        this.root = root;
-    }
-    scopeDirName(scope) {
-        const slug = scope
-            .toLowerCase()
-            .replace(/[^a-z0-9-]+/g, "-")
-            .replace(/^-+|-+$/g, "")
-            .slice(0, SCOPE_SLUG_MAX);
-        const h = createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 24);
-        return `${slug || "s"}-${h}`;
-    }
-    scopeDirPath(scope) {
-        return join(this.root, this.scopeDirName(scope));
-    }
-    assertScopeDirSafe(dir) {
-        let st;
-        try {
-            st = lstatSync(dir);
-        }
-        catch (err) {
-            if (err.code === "ENOENT")
-                return;
-            throw err;
-        }
-        if (st.isSymbolicLink() || !st.isDirectory()) {
-            const e = new Error(`FileStrategyStore: scope directory ${dir} is not a plain directory (symlink or non-dir refused)`);
-            e.code = "strategy.scope_dir_invalid";
-            throw e;
-        }
-    }
-    incident(i) {
-        const sink = this.onIncident;
-        if (sink !== undefined) {
-            const site = `FileStrategyStore.onIncident.${i.op}`;
-            this.sinkNotifier.notify(() => observeThenableRejection(sink(i), this.sinkNotifier, site), site);
-            return;
-        }
-        if (!this.warnedOps.has(i.op)) {
-            this.warnedOps.add(i.op);
-            console.warn(`FileStrategyStore ${i.op} incident: ${i.error}${i.path !== undefined ? ` (${i.path})` : ""}`);
-        }
-    }
-    sweepStaleTemps(dir) {
-        if (this.sweptTemps.has(dir))
-            return;
-        this.sweptTemps.add(dir);
-        let names;
-        try {
-            names = readdirSync(dir);
-        }
-        catch {
-            return;
-        }
-        const cutoff = Date.now() - STALE_TEMP_MS;
-        for (const name of names) {
-            if (!name.endsWith(".tmp"))
-                continue;
-            const p = join(dir, name);
-            try {
-                if (statSync(p).mtimeMs < cutoff)
-                    unlinkSync(p);
-            }
-            catch {
-            }
-        }
-    }
-    loadScope(scope, dir, readCap) {
-        let names;
-        try {
-            names = readdirSync(dir);
-        }
-        catch (err) {
-            if (err.code === "ENOENT")
-                return [];
-            throw err;
-        }
-        let candidates = names.filter((n) => FILE_RE.test(n)).sort();
-        if (Number.isFinite(readCap) && candidates.length > readCap) {
-            this.incident({
-                op: "find",
-                error: `scope directory holds ${candidates.length} entry files, over the ${readCap} read cap — parsing the first ${readCap} only (an external writer likely inflated this directory)`,
-                path: dir,
-            });
-            candidates = candidates.slice(0, readCap);
-        }
-        const out = [];
-        for (const name of candidates) {
-            const p = join(dir, name);
-            let fst;
-            try {
-                fst = lstatSync(p);
-            }
-            catch (err) {
-                if (err.code === "ENOENT")
-                    continue;
-                this.incident({ op: "find", error: `unstat-able entry skipped: ${thrownText(err)}`, path: p });
-                continue;
-            }
-            if (!fst.isFile()) {
-                this.incident({ op: "find", error: "non-regular entry skipped (symlink or special file refused)", path: p });
-                continue;
-            }
-            if (fst.size > MAX_ENTRY_FILE_BYTES) {
-                this.quarantine(p, `entry file is ${fst.size} bytes, over the ${MAX_ENTRY_FILE_BYTES} read bound`);
-                continue;
-            }
-            let raw;
-            try {
-                raw = readFileSync(p, "utf8");
-            }
-            catch (err) {
-                if (err.code === "ENOENT")
-                    continue;
-                this.incident({ op: "find", error: `unreadable entry skipped: ${thrownText(err)}`, path: p });
-                continue;
-            }
-            let parsed;
-            try {
-                parsed = JSON.parse(raw);
-            }
-            catch {
-                this.quarantine(p, "unparseable JSON");
-                continue;
-            }
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-                this.quarantine(p, "top-level JSON value is not an object");
-                continue;
-            }
-            const rec = parsed;
-            if (rec.v !== 1) {
-                this.incident({ op: "parse", error: `unknown schema version ${String(rec.v)} — entry skipped, file left in place`, path: p });
-                continue;
-            }
-            const { v: _v, ...candidate } = rec;
-            const issue = storedStrategyShapeIssue(candidate);
-            if (issue !== null) {
-                this.quarantine(p, issue);
-                continue;
-            }
-            const entry = candidate;
-            const fileId = FILE_RE.exec(name)[1];
-            if (entry.scope !== scope || entry.id !== fileId) {
-                this.incident({
-                    op: "find",
-                    error: `entry skipped: scope/id mismatch (file claims scope ${JSON.stringify(entry.scope)}, id ${JSON.stringify(entry.id)})`,
-                    id: fileId,
-                    path: p,
-                });
-                continue;
-            }
-            out.push({ entry, path: p });
-        }
-        const byKey = new Map();
-        for (const le of out) {
-            const key = strategyDedupKey(le.entry);
-            const prev = byKey.get(key);
-            if (prev === undefined || scoreStoredStrategy(le.entry) > scoreStoredStrategy(prev.entry))
-                byKey.set(key, le);
-        }
-        return [...byKey.values()];
-    }
-    quarantine(p, reason) {
-        try {
-            renameSync(p, `${p}.bad`);
-            this.incident({ op: "parse", error: `corrupt entry quarantined (${reason})`, path: p });
-        }
-        catch (err) {
-            this.incident({ op: "parse", error: `corrupt entry skipped (${reason}); quarantine rename failed: ${thrownText(err)}`, path: p });
-        }
-    }
-    writeEntry(dir, path, entry) {
-        const record = {
-            v: 1,
-            id: entry.id,
-            problem: entry.problem,
-            strategy: entry.strategy,
-            confidence: entry.confidence,
-            scope: entry.scope,
-            ts: entry.ts,
-            ...(entry.teacherModel !== undefined ? { teacherModel: entry.teacherModel } : {}),
-            ...(entry.signature !== undefined ? { signature: entry.signature } : {}),
-            ...(entry.origin !== undefined ? { origin: entry.origin } : {}),
-        };
-        const bytes = JSON.stringify(record);
-        if (Buffer.byteLength(bytes, "utf8") > MAX_ENTRY_FILE_BYTES) {
-            const e = new Error(`FileStrategyStore: entry serializes over the ${MAX_ENTRY_FILE_BYTES}-byte read bound (JSON escaping expanded it past the field caps) — refusing a write the read side would quarantine`);
-            e.code = "strategy.entry_invalid";
-            throw e;
-        }
-        atomicWriteFile(dir, path, bytes);
-    }
-    save(s) {
-        validateStrategyForWrite(s);
-        const dir = this.scopeDirPath(s.scope);
-        this.assertScopeDirSafe(dir);
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
-        this.sweepStaleTemps(dir);
-        const existing = this.loadScope(s.scope, dir, this.retrievalReadCap());
-        const key = strategyDedupKey(s);
-        const dup = existing.find((le) => strategyDedupKey(le.entry) === key);
-        let all;
-        if (dup !== undefined) {
-            const refreshed = {
-                ...dup.entry,
-                ...(s.confidence >= dup.entry.confidence ? { confidence: s.confidence, ts: s.ts } : {}),
-                ...(s.teacherModel !== undefined ? { teacherModel: s.teacherModel } : {}),
-            };
-            this.writeEntry(dir, dup.path, refreshed);
-            dup.entry = refreshed;
-            all = existing;
-        }
-        else {
-            const p = join(dir, `${s.id}.json`);
-            const byId = existing.find((le) => le.entry.id === s.id);
-            this.writeEntry(dir, p, s);
-            if (byId !== undefined) {
-                byId.entry = s;
-                all = existing;
-            }
-            else {
-                all = [...existing, { entry: s, path: p }];
-            }
-        }
-        if (all.length > this.maxPerScope) {
-            this.evict(all, this.maxPerScope);
-        }
-    }
-    evict(all, keep) {
-        const sorted = [...all].sort((a, b) => scoreStoredStrategy(b.entry) - scoreStoredStrategy(a.entry));
-        for (const le of sorted.slice(keep)) {
-            try {
-                unlinkSync(le.path);
-            }
-            catch (err) {
-                if (err.code === "ENOENT")
-                    continue;
-                this.incident({ op: "evict", error: thrownText(err), id: le.entry.id, path: le.path });
-            }
-        }
-    }
-    find(scope, query, limit) {
-        const cap = resolveFindLimit(limit);
-        const dir = this.scopeDirPath(scope);
-        this.assertScopeDirSafe(dir);
-        const matches = compileStrategyQuery(query);
-        if (matches === null)
-            return [];
-        const ranked = this.loadScope(scope, dir, this.retrievalReadCap())
-            .map((le) => le.entry)
-            .filter((e) => matches(e.problem))
-            .sort((a, b) => scoreStoredStrategy(b) - scoreStoredStrategy(a))
-            .slice(0, cap);
-        let bytes = 0;
-        for (let i = 0; i < ranked.length; i++) {
-            bytes += Buffer.byteLength(ranked[i].strategy, "utf8");
-            if (bytes > MAX_STRATEGY_INJECTION_TOTAL_BYTES) {
-                this.incident({
-                    op: "find",
-                    error: `result truncated at ${i} of ${ranked.length} entries — combined strategy text exceeded ${MAX_STRATEGY_INJECTION_TOTAL_BYTES} bytes (per-entry cap ${MAX_STRATEGY_TEXT_BYTES})`,
-                });
-                return ranked.slice(0, i);
-            }
-        }
-        return ranked;
-    }
-    retrievalReadCap() {
-        return this.maxPerScope * READ_FILE_CAP_FACTOR;
-    }
-    prune(scope, maxSize) {
-        const n = resolveCapacityCap("maxSize", maxSize);
-        const dir = this.scopeDirPath(scope);
-        this.assertScopeDirSafe(dir);
-        const all = this.loadScope(scope, dir, Number.POSITIVE_INFINITY);
-        if (all.length > n)
-            this.evict(all, n);
-    }
-    scopeUsage(scope) {
-        const dir = this.scopeDirPath(scope);
-        this.assertScopeDirSafe(dir);
-        return { used: this.loadScope(scope, dir, Number.POSITIVE_INFINITY).length, capacity: this.maxPerScope };
-    }
-    hasStrategy(scope, entry) {
-        const dir = this.scopeDirPath(scope);
-        this.assertScopeDirSafe(dir);
-        const key = strategyDedupKey(entry);
-        return this.loadScope(scope, dir, this.retrievalReadCap()).some((le) => strategyDedupKey(le.entry) === key);
-    }
-}