@pella-labs/pinakes 0.1.0

package/dist/sandbox/bindings/kg.js

@@ -0,0 +1,323 @@
+import { Scope } from 'quickjs-emscripten';
+import { nextReader } from '../../db/client.js';
+import { ftsQuery as ftsQueryImpl } from '../../retrieval/fts.js';
+import { vecQuery as vecQueryImpl } from '../../retrieval/vec.js';
+import { rrfFuse } from '../../retrieval/hybrid.js';
+import { writeWikiFile, appendWikiLog, removeWikiFile } from './write.js';
+import { queryGaps } from '../../gaps/detector.js';
+import { errorMessage, marshalJsValue } from '../helpers.js';
+/**
+ * Install the `kg` global with `kg.project.*` and/or `kg.personal.*`
+ * bindings plus backward-compat `kg.search()` / `kg.get()` aliases
+ * and `kg.describe()`.
+ *
+ * **Privacy invariant**: if `personalDeps` is undefined, `kg.personal`
+ * does NOT exist in the sandbox — not undefined, not null, simply absent.
+ * This is enforced at the dispatcher level (tool handler decides which
+ * deps to pass). The 15-test adversarial suite verifies this.
+ */
+export function installKgBindings(context, projectDeps, personalDeps) {
+    Scope.withScope((s) => {
+        const kgObj = s.manage(context.newObject());
+        // Install project namespace if deps provided
+        if (projectDeps) {
+            const projectObj = s.manage(context.newObject());
+            installScopeBindings(context, s, projectObj, projectDeps);
+            context.setProp(kgObj, 'project', projectObj);
+            // Backward-compat aliases route to project scope
+            installBackwardCompat(context, kgObj, projectDeps);
+        }
+        // Install personal namespace if deps provided (privacy invariant)
+        if (personalDeps) {
+            const personalObj = s.manage(context.newObject());
+            installScopeBindings(context, s, personalObj, personalDeps);
+            context.setProp(kgObj, 'personal', personalObj);
+        }
+        // kg.describe() — returns metadata for available scopes only
+        attachFn(context, kgObj, 'describe', () => {
+            const result = {};
+            if (projectDeps) {
+                result.project = describeScope(projectDeps);
+            }
+            if (personalDeps) {
+                result.personal = describeScope(personalDeps);
+            }
+            return result;
+        });
+        context.setProp(context.global, 'kg', kgObj);
+    });
+}
+/**
+ * Install all bindings for one scope onto a QuickJS object.
+ * Called once for project, once for personal (if both are requested).
+ */
+function installScopeBindings(context, s, scopeObj, deps) {
+    const { bundle, scope } = deps;
+    const reader = nextReader(bundle);
+    const logObj = s.manage(context.newObject());
+    // -- fts(query, opts?) -------------------------------------------------
+    attachFn(context, scopeObj, 'fts', (args) => {
+        const query = args[0];
+        if (typeof query !== 'string' || !query.trim())
+            return [];
+        const opts = (args[1] ?? {});
+        const limit = Math.min(Math.max(opts.limit ?? 20, 1), 100);
+        return ftsQueryImpl(reader, scope, query, limit);
+    });
+    // -- vec(query, opts?) -------------------------------------------------
+    attachFn(context, scopeObj, 'vec', (args) => {
+        const query = args[0];
+        if (typeof query !== 'string' || !query.trim())
+            return [];
+        const opts = (args[1] ?? {});
+        const limit = Math.min(Math.max(opts.limit ?? 20, 1), 100);
+        const cached = deps.queryEmbeddings?.get(query);
+        if (!cached)
+            return [];
+        return vecQueryImpl(reader, scope, cached, limit);
+    });
+    // -- hybrid(query, opts?) ----------------------------------------------
+    attachFn(context, scopeObj, 'hybrid', (args) => {
+        const query = args[0];
+        if (typeof query !== 'string' || !query.trim())
+            return [];
+        const opts = (args[1] ?? {});
+        const limit = Math.min(Math.max(opts.limit ?? 20, 1), 100);
+        const rrfK = opts.rrf_k ?? 60;
+        const fetchLimit = Math.min(limit * 2, 100);
+        const ftsResults = ftsQueryImpl(reader, scope, query, fetchLimit);
+        const cached = deps.queryEmbeddings?.get(query);
+        const vecResults = cached
+            ? vecQueryImpl(reader, scope, cached, fetchLimit)
+            : [];
+        return rrfFuse(ftsResults, vecResults, rrfK, limit);
+    });
+    // -- get(id) -----------------------------------------------------------
+    attachFn(context, scopeObj, 'get', (args) => {
+        const id = args[0];
+        if (typeof id !== 'string')
+            return null;
+        return nodeGet(reader, scope, id);
+    });
+    // -- index(opts?) — Phase 7.5: browsable table of contents ---------------
+    attachFn(context, scopeObj, 'index', (args) => {
+        const opts = (args[0] ?? {});
+        const limit = Math.min(Math.max(opts.limit ?? 500, 1), 2000);
+        return indexQuery(reader, scope, limit, opts.kind, opts.source_uri);
+    });
+    // -- neighbors(id, opts?) ----------------------------------------------
+    attachFn(context, scopeObj, 'neighbors', (args) => {
+        const id = args[0];
+        if (typeof id !== 'string')
+            return [];
+        const opts = (args[1] ?? {});
+        const depth = Math.min(Math.max(opts.depth ?? 1, 1), 3);
+        return neighborsQuery(reader, scope, id, depth, opts.edge_kinds);
+    });
+    // -- log.recent(n?, opts?) ---------------------------------------------
+    attachFn(context, logObj, 'recent', (args) => {
+        const n = typeof args[0] === 'number' ? Math.min(Math.max(args[0], 1), 100) : 20;
+        const opts = (args[1] ?? {});
+        return logRecent(reader, scope, n, opts.kind);
+    });
+    // -- gaps(opts?) — Phase 6: query kg_gaps for concept gaps ---------------
+    attachFn(context, scopeObj, 'gaps', (args) => {
+        const opts = (args[0] ?? {});
+        return queryGaps(reader, scope, opts);
+    });
+    // -- write(path, content) ----------------------------------------------
+    attachThrowingFn(context, scopeObj, 'write', (args) => {
+        if (!deps.wikiRoot || !deps.writeCounter) {
+            throw new Error('write bindings not available (no wikiRoot configured)');
+        }
+        const path = args[0];
+        const content = args[1];
+        if (typeof path !== 'string')
+            throw new Error('write: path must be a string');
+        if (typeof content !== 'string')
+            throw new Error('write: content must be a string');
+        return writeWikiFile(deps.wikiRoot, path, content, deps.writeCounter, scope, bundle.writer);
+    });
+    // -- append(entry) -----------------------------------------------------
+    attachThrowingFn(context, scopeObj, 'append', (args) => {
+        if (!deps.wikiRoot || !deps.writeCounter) {
+            throw new Error('append bindings not available (no wikiRoot configured)');
+        }
+        const entry = args[0];
+        if (typeof entry !== 'string')
+            throw new Error('append: entry must be a string');
+        return appendWikiLog(deps.wikiRoot, entry, deps.writeCounter, scope, bundle.writer);
+    });
+    // -- remove(path) ------------------------------------------------------
+    attachThrowingFn(context, scopeObj, 'remove', (args) => {
+        if (!deps.wikiRoot || !deps.writeCounter) {
+            throw new Error('remove bindings not available (no wikiRoot configured)');
+        }
+        const path = args[0];
+        if (typeof path !== 'string')
+            throw new Error('remove: path must be a string');
+        return removeWikiFile(deps.wikiRoot, path, deps.writeCounter, scope, bundle.writer);
+    });
+    // Wire nesting: scope.log
+    context.setProp(scopeObj, 'log', logObj);
+}
+/**
+ * Install backward-compat `kg.search()` and `kg.get()` aliases.
+ * Always routes to the project scope.
+ */
+function installBackwardCompat(context, kgObj, deps) {
+    const { repository, scope } = deps;
+    attachFn(context, kgObj, 'search', (args) => {
+        const query = args[0];
+        if (typeof query !== 'string')
+            return [];
+        return repository.search(query, scope).map((c) => ({
+            id: c.id,
+            text: c.text,
+            source_uri: c.source_uri,
+        }));
+    });
+    attachFn(context, kgObj, 'get', (args) => {
+        const id = args[0];
+        if (typeof id !== 'string')
+            return null;
+        const c = repository.get(id, scope);
+        if (!c)
+            return null;
+        return { id: c.id, text: c.text, source_uri: c.source_uri };
+    });
+}
+/**
+ * Return summary metadata for a scope (no content, just counts).
+ */
+function describeScope(deps) {
+    const reader = nextReader(deps.bundle);
+    const chunks = reader
+        .prepare(`SELECT count(*) AS c FROM kg_chunks ch JOIN kg_nodes n ON ch.node_id = n.id WHERE n.scope = ?`)
+        .get(deps.scope)?.c ?? 0;
+    const nodes = reader
+        .prepare(`SELECT count(*) AS c FROM kg_nodes WHERE scope = ?`)
+        .get(deps.scope)?.c ?? 0;
+    return { chunks, nodes };
+}
+// ============================================================================
+// SQL query implementations
+// ============================================================================
+function nodeGet(reader, scope, id) {
+    const row = reader
+        .prepare(`SELECT id, source_uri, section_path, kind, title, content, token_count, confidence
+         FROM kg_nodes
+        WHERE id = ? AND scope = ?
+        LIMIT 1`)
+        .get(id, scope);
+    return row ?? null;
+}
+function indexQuery(reader, scope, limit, kind, sourceUri) {
+    let sql = `SELECT id, title, source_uri, section_path, kind, token_count
+     FROM kg_nodes
+    WHERE scope = ?`;
+    const params = [scope];
+    if (kind) {
+        sql += ` AND kind = ?`;
+        params.push(kind);
+    }
+    if (sourceUri) {
+        sql += ` AND source_uri = ?`;
+        params.push(sourceUri);
+    }
+    sql += ` ORDER BY source_uri, section_path LIMIT ?`;
+    params.push(limit);
+    return reader.prepare(sql).all(...params);
+}
+function neighborsQuery(reader, scope, id, maxDepth, edgeKinds) {
+    let edgeFilter = '';
+    const params = [id, maxDepth];
+    if (edgeKinds && edgeKinds.length > 0) {
+        const placeholders = edgeKinds.map(() => '?').join(',');
+        edgeFilter = `AND e.edge_kind IN (${placeholders})`;
+        params.push(...edgeKinds);
+    }
+    params.push(id, scope);
+    const sql = `
+    WITH RECURSIVE hops(node_id, depth) AS (
+      VALUES(?, 0)
+      UNION ALL
+      SELECT e.dst_id, h.depth + 1
+        FROM hops h
+        JOIN kg_edges e ON e.src_id = h.node_id
+       WHERE h.depth < ? ${edgeFilter}
+    )
+    SELECT DISTINCT n.id, n.source_uri, n.section_path, n.kind, n.title, h.depth
+      FROM hops h
+      JOIN kg_nodes n ON n.id = h.node_id
+     WHERE n.id != ? AND n.scope = ?`;
+    return reader.prepare(sql).all(...params);
+}
+function logRecent(reader, scope, n, kind) {
+    let sql;
+    let params;
+    if (kind) {
+        sql = `SELECT id, ts, kind, source_uri, payload
+             FROM kg_log
+            WHERE scope = ? AND kind = ?
+            ORDER BY ts DESC
+            LIMIT ?`;
+        params = [scope, kind, n];
+    }
+    else {
+        sql = `SELECT id, ts, kind, source_uri, payload
+             FROM kg_log
+            WHERE scope = ?
+            ORDER BY ts DESC
+            LIMIT ?`;
+        params = [scope, n];
+    }
+    const rows = reader.prepare(sql).all(...params);
+    return rows.map((r) => ({
+        id: r.id,
+        ts: r.ts,
+        kind: r.kind,
+        source_uri: r.source_uri,
+        payload: r.payload ? tryParseJson(r.payload) : null,
+    }));
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function tryParseJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
+}
+function attachFn(context, obj, name, impl) {
+    const fn = context.newFunction(name, (...handles) => {
+        try {
+            const nativeArgs = handles.map((h) => context.dump(h));
+            const result = impl(nativeArgs);
+            return marshalJsValue(context, result);
+        }
+        catch (e) {
+            return context.newError(errorMessage(e));
+        }
+    });
+    context.setProp(obj, name, fn);
+    fn.dispose();
+}
+function attachThrowingFn(context, obj, name, impl) {
+    const fn = context.newFunction(name, (...handles) => {
+        try {
+            const nativeArgs = handles.map((h) => context.dump(h));
+            const result = impl(nativeArgs);
+            return marshalJsValue(context, result);
+        }
+        catch (e) {
+            return { error: context.newError(errorMessage(e)) };
+        }
+    });
+    context.setProp(obj, name, fn);
+    fn.dispose();
+}
+//# sourceMappingURL=kg.js.map

package/dist/sandbox/bindings/kg.js.map

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

package/dist/sandbox/bindings/logger.d.ts

@@ -0,0 +1,11 @@
+import { type QuickJSContext } from 'quickjs-emscripten';
+/**
+ * Install `logger.log(...)` capture on a QuickJS context.
+ *
+ * Every call to `logger.log(arg1, arg2, ...)` inside the guest appends a
+ * single string to `logs`. Arguments are dumped from QuickJS handles and
+ * joined with spaces — strings pass through as-is, everything else is
+ * JSON-stringified.
+ */
+export declare function installLogger(context: QuickJSContext, logs: string[]): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/sandbox/bindings/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/sandbox/bindings/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,cAAc,EAAsB,MAAM,oBAAoB,CAAC;AAGpF;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAsB3E"}

package/dist/sandbox/bindings/logger.js

@@ -0,0 +1,33 @@
+import { Scope } from 'quickjs-emscripten';
+import { errorMessage } from '../helpers.js';
+/**
+ * Install `logger.log(...)` capture on a QuickJS context.
+ *
+ * Every call to `logger.log(arg1, arg2, ...)` inside the guest appends a
+ * single string to `logs`. Arguments are dumped from QuickJS handles and
+ * joined with spaces — strings pass through as-is, everything else is
+ * JSON-stringified.
+ */
+export function installLogger(context, logs) {
+    Scope.withScope((scope) => {
+        const loggerObj = scope.manage(context.newObject());
+        const logFn = context.newFunction('log', (...argsHandles) => {
+            try {
+                const parts = [];
+                for (const h of argsHandles) {
+                    const dumped = context.dump(h);
+                    parts.push(typeof dumped === 'string' ? dumped : JSON.stringify(dumped));
+                }
+                logs.push(parts.join(' '));
+            }
+            catch (e) {
+                logs.push(`<logger.log serialization error: ${errorMessage(e)}>`);
+            }
+            return context.undefined;
+        });
+        context.setProp(loggerObj, 'log', logFn);
+        logFn.dispose();
+        context.setProp(context.global, 'logger', loggerObj);
+    });
+}
+//# sourceMappingURL=logger.js.map

package/dist/sandbox/bindings/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/sandbox/bindings/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAA2C,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,OAAuB,EAAE,IAAc;IACnE,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QACxB,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;QAEpD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,GAAG,WAA4B,EAAE,EAAE;YAC3E,IAAI,CAAC;gBACH,MAAM,KAAK,GAAa,EAAE,CAAC;gBAC3B,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;oBAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;oBAC/B,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3E,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAC7B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,IAAI,CAAC,oCAAoC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACpE,CAAC;YACD,OAAO,OAAO,CAAC,SAAS,CAAC;QAC3B,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACzC,KAAK,CAAC,OAAO,EAAE,CAAC;QAEhB,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/sandbox/bindings/write.d.ts

@@ -0,0 +1,34 @@
+import type { Database as BetterSqliteDatabase } from 'better-sqlite3';
+/** Mutable counter shared across all write operations in a single kg_execute call. */
+export interface WriteCounter {
+    value: number;
+}
+/**
+ * Create or overwrite a wiki page. Atomic write via tmp + rename.
+ *
+ * @returns `{ path: string, bytes: number }` — the relative path and byte count.
+ */
+export declare function writeWikiFile(wikiRoot: string, rawPath: string, content: string, counter: WriteCounter, scope: string, writer: BetterSqliteDatabase): {
+    path: string;
+    bytes: number;
+};
+/**
+ * Append a timestamped entry to `<wikiRoot>/log.md`.
+ *
+ * @returns `{ path: string, bytes: number }` — always `log.md`.
+ */
+export declare function appendWikiLog(wikiRoot: string, entry: string, counter: WriteCounter, scope: string, writer: BetterSqliteDatabase): {
+    path: string;
+    bytes: number;
+};
+/**
+ * Remove a wiki page from disk. Chokidar `unlink` event triggers
+ * ingester removal of the corresponding nodes/chunks.
+ *
+ * @returns `{ path: string, removed: true }`.
+ */
+export declare function removeWikiFile(wikiRoot: string, rawPath: string, counter: WriteCounter, scope: string, writer: BetterSqliteDatabase): {
+    path: string;
+    removed: true;
+};
+//# sourceMappingURL=write.d.ts.map

package/dist/sandbox/bindings/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/sandbox/bindings/write.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAsBvE,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAmGD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,oBAAoB,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAqCjC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,oBAAoB,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA2CjC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,oBAAoB,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAgBjC"}

package/dist/sandbox/bindings/write.js

@@ -0,0 +1,195 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, normalize, resolve, sep } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { logger } from '../../observability/logger.js';
+/**
+ * Write-path bindings for `kg.project.write()`, `kg.project.append()`,
+ * and `kg.project.remove()` (CLAUDE.md §Architecture #6, presearch D35).
+ *
+ * **Write contract**:
+ *   1. Path containment: resolved path must start with `wikiRoot`
+ *   2. Extension: only `.md` files
+ *   3. Size: max `KG_MAX_WRITE_SIZE` bytes (default 100KB)
+ *   4. Rate: max 20 writes per `kg_execute` call
+ *   5. Atomic: tmp file + rename (never half-written files)
+ *   6. Audit: every write appends to `kg_log`
+ *
+ * Chokidar picks up the written file and triggers re-indexing automatically.
+ */
+const MAX_WRITE_SIZE = parseInt(process.env['KG_MAX_WRITE_SIZE'] ?? '102400', 10);
+const MAX_WRITES_PER_CALL = 20;
+// ============================================================================
+// Path sanitization
+// ============================================================================
+/**
+ * Sanitize and resolve a user-provided path against the wiki root.
+ * Throws if the path escapes the wiki root or violates constraints.
+ */
+function sanitizePath(wikiRoot, rawPath) {
+    if (!rawPath || typeof rawPath !== 'string') {
+        throw new Error('path is required and must be a non-empty string');
+    }
+    // Reject absolute paths
+    if (isAbsolute(rawPath)) {
+        throw new Error(`absolute paths are not allowed: ${rawPath}`);
+    }
+    // Normalize and check for .. traversal
+    const normalized = normalize(rawPath);
+    const parts = normalized.split(sep);
+    if (parts.some((p) => p === '..')) {
+        throw new Error(`path traversal (..) is not allowed: ${rawPath}`);
+    }
+    // Ensure .md extension
+    if (!normalized.endsWith('.md')) {
+        throw new Error(`only .md files can be written (got: ${rawPath})`);
+    }
+    // Resolve against wiki root
+    const resolved = resolve(wikiRoot, normalized);
+    // Containment check: resolved path must start with wikiRoot
+    if (!resolved.startsWith(wikiRoot + sep) && resolved !== wikiRoot) {
+        throw new Error(`path escapes wiki root: ${rawPath}`);
+    }
+    // Symlink check: if the target already exists, verify its real path
+    if (existsSync(resolved)) {
+        try {
+            const stat = lstatSync(resolved);
+            if (stat.isSymbolicLink()) {
+                const real = realpathSync(resolved);
+                if (!real.startsWith(wikiRoot + sep) && real !== wikiRoot) {
+                    throw new Error(`symlink escapes wiki root: ${rawPath} → ${real}`);
+                }
+            }
+        }
+        catch (e) {
+            if (e.message.includes('escapes wiki root'))
+                throw e;
+            // lstat errors on non-existent files are fine
+        }
+    }
+    return resolved;
+}
+// ============================================================================
+// Rate limiting
+// ============================================================================
+function checkRateLimit(counter) {
+    counter.value++;
+    if (counter.value > MAX_WRITES_PER_CALL) {
+        throw new Error(`write rate limit exceeded: max ${MAX_WRITES_PER_CALL} writes per kg_execute call (attempted #${counter.value})`);
+    }
+}
+// ============================================================================
+// Audit logging
+// ============================================================================
+function auditLog(writer, scope, kind, filePath, payload) {
+    try {
+        writer
+            .prepare(`INSERT INTO kg_log (ts, scope, kind, source_uri, payload)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(Date.now(), scope, kind, pathToFileURL(filePath).href, JSON.stringify(payload));
+    }
+    catch (err) {
+        logger.warn({ err, kind, filePath }, 'failed to append write audit to kg_log');
+    }
+}
+// ============================================================================
+// Write operations
+// ============================================================================
+/**
+ * Create or overwrite a wiki page. Atomic write via tmp + rename.
+ *
+ * @returns `{ path: string, bytes: number }` — the relative path and byte count.
+ */
+export function writeWikiFile(wikiRoot, rawPath, content, counter, scope, writer) {
+    checkRateLimit(counter);
+    const resolved = sanitizePath(wikiRoot, rawPath);
+    const bytes = Buffer.byteLength(content, 'utf-8');
+    if (bytes > MAX_WRITE_SIZE) {
+        throw new Error(`content exceeds max write size: ${bytes} bytes > ${MAX_WRITE_SIZE} bytes`);
+    }
+    // Ensure parent directory exists
+    const dir = dirname(resolved);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    // Atomic write: write to tmp file, then rename
+    const tmpPath = `${resolved}.tmp.${randomBytes(4).toString('hex')}`;
+    try {
+        writeFileSync(tmpPath, content, 'utf-8');
+        renameSync(tmpPath, resolved);
+    }
+    catch (err) {
+        // Clean up tmp file if rename failed
+        try {
+            if (existsSync(tmpPath))
+                unlinkSync(tmpPath);
+        }
+        catch { /* best effort */ }
+        throw err;
+    }
+    // Relative path for the response
+    const relativePath = resolved.slice(wikiRoot.length + 1);
+    auditLog(writer, scope, 'write', resolved, { bytes, relativePath });
+    return { path: relativePath, bytes };
+}
+/**
+ * Append a timestamped entry to `<wikiRoot>/log.md`.
+ *
+ * @returns `{ path: string, bytes: number }` — always `log.md`.
+ */
+export function appendWikiLog(wikiRoot, entry, counter, scope, writer) {
+    checkRateLimit(counter);
+    if (!entry || typeof entry !== 'string') {
+        throw new Error('entry is required and must be a non-empty string');
+    }
+    const logPath = resolve(wikiRoot, 'log.md');
+    const timestamp = new Date().toISOString();
+    const line = `- ${timestamp}: ${entry}\n`;
+    const lineBytes = Buffer.byteLength(line, 'utf-8');
+    if (lineBytes > MAX_WRITE_SIZE) {
+        throw new Error(`entry exceeds max write size: ${lineBytes} bytes > ${MAX_WRITE_SIZE} bytes`);
+    }
+    // Read existing content (may not exist yet)
+    let existing = '';
+    if (existsSync(logPath)) {
+        existing = readFileSync(logPath, 'utf-8');
+    }
+    else {
+        existing = '# Turn log\n\n';
+    }
+    const newContent = existing + line;
+    // Atomic write
+    const tmpPath = `${logPath}.tmp.${randomBytes(4).toString('hex')}`;
+    try {
+        writeFileSync(tmpPath, newContent, 'utf-8');
+        renameSync(tmpPath, logPath);
+    }
+    catch (err) {
+        try {
+            if (existsSync(tmpPath))
+                unlinkSync(tmpPath);
+        }
+        catch { /* best effort */ }
+        throw err;
+    }
+    auditLog(writer, scope, 'append', logPath, { entry, bytes: lineBytes });
+    return { path: 'log.md', bytes: lineBytes };
+}
+/**
+ * Remove a wiki page from disk. Chokidar `unlink` event triggers
+ * ingester removal of the corresponding nodes/chunks.
+ *
+ * @returns `{ path: string, removed: true }`.
+ */
+export function removeWikiFile(wikiRoot, rawPath, counter, scope, writer) {
+    checkRateLimit(counter);
+    const resolved = sanitizePath(wikiRoot, rawPath);
+    if (!existsSync(resolved)) {
+        throw new Error(`file does not exist: ${rawPath}`);
+    }
+    const relativePath = resolved.slice(wikiRoot.length + 1);
+    unlinkSync(resolved);
+    auditLog(writer, scope, 'remove', resolved, { relativePath });
+    return { path: relativePath, removed: true };
+}
+//# sourceMappingURL=write.js.map

package/dist/sandbox/bindings/write.js.map

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