renor-engine 0.0.0-stage → 1.0.0

package/NOTICE

@@ -0,0 +1,73 @@
+Copyright 2026 Patrick Passos
+
+Renor's own work in this tree is licensed under the GNU Affero General
+Public License, Version 3 (AGPL-3.0-only). See the LICENSE file.
+
+Files imported from the public project obsidian-semantic-memory
+(https://github.com/sterben-enec/obsidian-semantic-memory) stay under
+that project's ISC license. The upstream notice is reproduced below
+unchanged. It is not an AGPL-3.0 grant, and the upstream copyright
+line is not Renor's.
+
+-----
+
+ISC License
+
+Copyright (c) 2026 sterben_enec
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+-----
+
+Third-party components
+
+@img/sharp-libvips-linux-x64 and the musl build (@img/sharp-libvips-linuxmusl-x64)
+are LGPL-3.0-or-later. @img/sharp-wasm32 is Apache-2.0 AND LGPL-3.0-or-later
+AND MIT. The sharp override in package.json pulls them in so
+@xenova/transformers can run a local embedding model. They ship as separate
+shared objects, not as AGPL-3.0 source. LGPL-3.0 stays compatible with
+this AGPL-3.0-only program while those libraries remain separate and this
+notice is kept. They are not AGPL-3.0.
+
+Token vocabulary (src/indexer/o200k.json)
+
+The file src/indexer/o200k.json holds the o200k_base token vocabulary packed
+from the copy that the gpt-tokenizer package ships (https://github.com/niieani/gpt-tokenizer),
+by scripts/tokenizer/gen-o200k.cjs. The license of that package is reproduced
+below unchanged.
+
+-----
+
+MIT License
+
+Copyright (c) 2023-2024 Bazyli Brzoska
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-----

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# Renor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![Claude Code saves a decision to Renor; a fresh Codex session recalls it](docs/assets/renor-readme-demo.gif)\
+*Self-hosted Renor, real session: Claude Code saves a decision, a fresh Codex session recalls it. Waiting time sped up.*
+
+[![engine-public-ci](https://github.com/patrickpassosb/renor-engine/actions/workflows/engine-public-ci.yml/badge.svg?branch=main)](https://github.com/patrickpassosb/renor-engine/actions/workflows/engine-public-ci.yml)
+
+**Renor is memory for coding agents: it keeps what you tell Claude Code, Codex or Cursor in a folder of Markdown files on your machine, and serves it back to any of them over MCP.**
+
+Every new agent session starts from zero: you re-explain the project, last week's decision and why, the thing you corrected twice. With Renor, one agent saves it and the next one finds it. The memory is plain files you own. It runs locally, needs no account or API key, and sends nothing off your machine unless you configure a model. A hosted version with no install is at <https://renor.cloud>.
+
+## Quickstart
+
+You need **Node 22** and git. The install is the only step that needs the network.
+
+```bash
+git clone https://github.com/patrickpassosb/renor-engine.git
+cd renor-engine
+node -v                    # must print v22.x
+npm ci && npm rebuild better-sqlite3 --ignore-scripts=false && npm run build
+node scripts/smoke-self-hosted.mjs
+```
+
+The last command starts the MCP server, saves one fact (`Ada favorite_color cerulean`), searches for it three ways and stops. It works in a temporary folder that it deletes afterwards, so it never touches your notes. It ends with:
+
+```text
+PASS: self-hosted stdio MCP can remember and retrieve a current fact.
+```
+
+Downloaded a ZIP instead of cloning? It has no git history to stamp the build with, so build with `RENOR_BUILD_COMMIT=0000000 npm run build` instead. A wrong Node version or skipped install scripts: see [Troubleshooting](docs/self-hosting.md#troubleshooting).
+
+## Connect your agent
+
+**Without a clone.** With Node 22 installed, one line registers the published package. Your notes go to a hidden `.renor` folder in your home directory (`~/.renor`, printed on stderr at start; it never reuses an existing `renor` folder); to use another folder, add `-e VAULT_PATH=/absolute/path` to the `claude` line or `--env VAULT_PATH=/absolute/path` to the `codex` line. The first start downloads about 130 MB and takes about 15 seconds; if your agent shows one failed connection, restart it.
+
+```bash
+claude mcp add --scope user renor-local -- npx -y renor-engine mcp
+codex mcp add renor-local -- npx -y renor-engine mcp
+```
+
+For Cursor or any other client, the server is the command `npx` with the arguments `-y renor-engine mcp`. `claude mcp remove renor-local` and `codex mcp remove renor-local` undo it. The rest of this section is the same thing from a clone, which also lets you change the code.
+
+**From a clone.**
+
+Pick a folder for your memory (a new, empty one is fine; an Obsidian vault works too) and index it. Run this, and the commands below, from the `renor-engine` directory in the same shell:
+
+```bash
+export VAULT_PATH="$HOME/renor-notes"    # absolute path; created if missing
+node dist/cli.js index
+```
+
+Each command below starts Renor with the Node 22 you are using now (`node -p process.execPath`), so the agent does not need Node 22 on its own `PATH`. In a new terminal, run the `export` line again first: each command stops with `VAULT_PATH: run the export line above first` rather than register a server that cannot start (an agent shows that only as "Connection closed").
+
+**Claude Code**
+
+```bash
+claude mcp add --scope user renor-local -e VAULT_PATH="${VAULT_PATH:?run the export line above first}" -- "$(node -p process.execPath)" "$PWD/dist/cli.js" mcp
+```
+
+Restart Claude Code; `/mcp` lists `renor-local` in every project. `claude mcp remove renor-local` undoes it.
+
+**Codex**
+
+```bash
+codex mcp add renor-local --env VAULT_PATH="${VAULT_PATH:?run the export line above first}" -- "$(node -p process.execPath)" "$PWD/dist/cli.js" mcp
+```
+
+Restart Codex; `codex mcp list` shows it. `codex mcp remove renor-local` undoes it.
+
+**Cursor**
+
+Cursor reads MCP servers from `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project). This prints the entry:
+
+```bash
+VAULT_PATH="${VAULT_PATH:?run the export line above first}" node -e 'console.log(JSON.stringify({ mcpServers: { "renor-local": { command: process.execPath,
+  args: [process.cwd() + "/dist/cli.js", "mcp"], env: { VAULT_PATH: process.env.VAULT_PATH } } } }, null, 2))'
+```
+
+Put it in that file, or merge the `renor-local` entry into an existing `mcpServers`, then check that `renor-local` is enabled in Cursor's MCP settings. (The `cursor-plugin/` folder of this repository is the Cursor plugin for the hosted service at renor.cloud, which needs a Renor account; it does not connect to this engine.)
+
+**Any other MCP client:** the command is `node dist/cli.js mcp` (stdio) with `VAULT_PATH` set.
+
+Then ask your agent to remember something, and ask about it in a new session. What an agent saves is searchable at once. A Markdown file you add or edit by hand is searchable after you run `node dist/cli.js index` again.
+
+## What is stored where
+
+| What | Where |
+| --- | --- |
+| Your notes | Any Markdown files in `$VAULT_PATH`. Renor reads them; edit them with anything. |
+| What agents save | Appended as Markdown in the same folder: facts to `System/Memory Events Ledger.md`, notes to `Memory/Daily/<date>.md`. |
+| Search index | SQLite at `$VAULT_PATH/.semantic-memory/index.db`. Derived: `node dist/cli.js index` rebuilds it from the Markdown. |
+
+Everything Renor keeps is in that one folder, so back it up, sync it or move it like any other folder. Nothing leaves your machine unless you set a model key: `EMBEDDING_PROVIDER=openai` sends your notes' text to OpenAI to embed it, and an evidence-model key (`RENOR_EVIDENCE_API_KEY` or an `OLLAMA_*` key) makes search send the notes it matched to that model. If your shell already exports such a key, add `-e RENOR_EVIDENCE_MODE=off` (Codex: `--env`) when you register the server. Every setting and its default: [docs/ENVIRONMENT-VARIABLES.md](docs/ENVIRONMENT-VARIABLES.md).
+
+**Search without embeddings.** With nothing set, Renor uses no embedding model, so a note is found by its exact words: `blue notebook` finds "The blue notebook is on the desk", but `where is my notebook?` does not. Saved facts are found either way. For search by meaning, set `EMBEDDING_PROVIDER=openai` with `OPENAI_API_KEY`, or `local` to download a model once and run it on this machine, then run `node dist/cli.js rebuild` so existing notes are embedded ([details](docs/self-hosting.md#embeddings)).
+
+## More
+
+- [docs/self-hosting.md](docs/self-hosting.md): troubleshooting, embeddings, the HTTP server with OAuth sign-in, connecting agents over HTTP, the tool lists, owner names, multi-agent ("hive") tools (set `RENOR_CONNECTION_NAME` per agent), and how the vault is protected.
+- [skill/SKILL.md](skill/SKILL.md): instructions to give your agent so it recalls and saves memory without being asked. Most of it names the hosted tools (`get_context`, `remember`); the `renor-local` server above has other names (`search`, `remember_fact`, `note`), listed in its [Stdio section](skill/SKILL.md#stdio-renor-engine-mcp).
+
+Renor is a single-owner engine: one person's notes, one set of agents. It is not a multi-user product.
+
+## Contributing, license, security
+
+Contributions are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers setup and tests and lists good first issues. Renor's own code is **AGPL-3.0-only** ([LICENSE](LICENSE)); files imported from the upstream project stay ISC ([NOTICE](NOTICE), [UPSTREAM.md](UPSTREAM.md)). Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md), not in a public issue.

package/dist/BUILD.json

@@ -0,0 +1,6 @@
+{
+  "commit": "19d71122d94bb2cd116cf594d23de16e7bdb2d7a",
+  "branch": "unknown",
+  "dirty": null,
+  "builtAt": "2026-10-20T20:23:44.240Z"
+}

package/dist/api/apiAuth.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_API_HOSTNAMES = exports.API_TOKEN_ENV = void 0;
+exports.requireApiToken = requireApiToken;
+exports.bearerTokenGuard = bearerTokenGuard;
+const crypto_1 = __importDefault(require("crypto"));
+/** Environment variable holding the bearer token every `renor serve` route requires. */
+exports.API_TOKEN_ENV = 'RENOR_API_TOKEN';
+/** Host names the local API answers to. Anything else is a page rebinding its own domain to loopback. */
+exports.LOCAL_API_HOSTNAMES = ['localhost', '127.0.0.1', '[::1]'];
+function digest(value) {
+    return crypto_1.default.createHash('sha256').update(value, 'utf8').digest();
+}
+/**
+ * The token `renor serve` was started with, or a refusal naming the variable. A local API with no
+ * credential is open to every user of the machine (loopback is shared), so there is no default and no
+ * "open" mode: an unset or blank token is a start failure.
+ */
+function requireApiToken(env = process.env) {
+    const token = env[exports.API_TOKEN_ENV]?.trim();
+    if (!token) {
+        throw new Error(`${exports.API_TOKEN_ENV} is not set. The HTTP API (renor serve) has no other protection: any user on this machine `
+            + 'can reach 127.0.0.1. Refusing to start without a bearer token (fail closed). '
+            + `Set ${exports.API_TOKEN_ENV} to a long random value (for example: export ${exports.API_TOKEN_ENV}=$(openssl rand -hex 32)) `
+            + 'and send it as "Authorization: Bearer <token>" on every request.');
+    }
+    return token;
+}
+/** Express middleware: `Authorization: Bearer <token>` is required, compared in constant time. */
+function bearerTokenGuard(token) {
+    const expected = digest(token);
+    return (req, res, next) => {
+        const header = req.headers.authorization;
+        const match = typeof header === 'string' ? /^Bearer +(.+)$/i.exec(header) : null;
+        if (match && crypto_1.default.timingSafeEqual(digest(match[1].trim()), expected))
+            return next();
+        res.set('WWW-Authenticate', 'Bearer');
+        res.status(401).json({ error: 'unauthorized' });
+    };
+}

package/dist/api/server.js

@@ -0,0 +1,172 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServer = createServer;
+const express_1 = __importDefault(require("express"));
+const hostHeaderValidation_js_1 = require("@modelcontextprotocol/sdk/server/middleware/hostHeaderValidation.js");
+const apiAuth_1 = require("./apiAuth");
+const orchestrator_1 = require("../retrieval/orchestrator");
+const ledgerPresentation_1 = require("../retrieval/ledgerPresentation");
+const entityLookup_1 = require("../retrieval/entityLookup");
+const writer_1 = require("../memory/writer");
+const lifecycle_1 = require("../memory/lifecycle");
+const attach_1 = require("../evidence/attach");
+const options_1 = require("../evidence/options");
+const composer_1 = require("../context/composer");
+const readHonesty_1 = require("../context/readHonesty");
+const buildIdentity_1 = require("../buildIdentity");
+function createServer(db, vectorIndex, provider, vaultPath, priorityPaths, memoryDir, ledgerPath, options) {
+    // Fail closed: there is no unauthenticated way to build this server.
+    const apiToken = options?.apiToken?.trim();
+    if (!apiToken)
+        throw new Error('createServer needs options.apiToken: the HTTP API does not run without a bearer token');
+    const app = (0, express_1.default)();
+    // DNS-rebinding guard first: a page that rebinds its own domain to 127.0.0.1 sends its own Host, and is refused
+    // before any route (or the token check) runs. Then the credential every other local user lacks.
+    app.use((0, hostHeaderValidation_js_1.hostHeaderValidation)(apiAuth_1.LOCAL_API_HOSTNAMES));
+    app.use((0, apiAuth_1.bearerTokenGuard)(apiToken));
+    app.use(express_1.default.json());
+    // Resolve the optional evidence path once per server, not once per request.
+    // This avoids opening a new SQLite evidence-cache connection on every search.
+    const productEvidenceEnabled = (0, attach_1.searchEvidenceEnabled)();
+    const productEvidenceOptions = productEvidenceEnabled
+        ? (0, options_1.resolveEvidenceToolOptions)({ dbPath: db.name })
+        : null;
+    const productEvidenceExtractor = productEvidenceOptions
+        ? (0, options_1.createEvidenceExtractor)(productEvidenceOptions)
+        : null;
+    // C0 shared composer (ADR-0003 §5): opt-in via RENOR_STRUCTURED_CONTEXT,
+    // default OFF — when off, responses are byte-identical to the pre-C0 contract.
+    const structuredOn = (0, composer_1.structuredContextEnabled)();
+    // Relative to the vault root — remember() joins it onto vaultPath.
+    const config_ledgerPath = ledgerPath ?? lifecycle_1.DEFAULT_LEDGER_REL;
+    // The ledger is the engine's own record, not a memory: this route returns neither its header nor the markup of its records.
+    const isLedger = (0, ledgerPresentation_1.ledgerNoteMatcher)({ memoryDir: vaultPath, ledgerRelPath: config_ledgerPath });
+    // Build/deploy identity: which source commit is this process running? Written
+    // at build time by scripts/ci/stamp-build.mjs and read through the shared,
+    // non-throwing helper (src/buildIdentity.ts) that the MVP's GET /version also
+    // uses. Deploy drift must be observable; the manifest never throws.
+    app.get('/api/health', (req, res) => {
+        res.json({ ok: true, name: 'renor', version: '1.0.0', ...(0, buildIdentity_1.readBuildIdentity)() });
+    });
+    app.post('/retrieve-context', async (req, res) => {
+        const { query, topK: rawTopK = 20 } = req.body;
+        if (!query)
+            return void res.status(400).json({ error: 'query required' });
+        const topK = Math.min(100, Math.max(1, Math.floor(Number(rawTopK) || 20)));
+        // LANE 3 read-time honesty (RENOR_READ_HONESTY, default OFF): provenance +
+        // contradiction + abstention alongside the unchanged hits array.
+        const readHonesty = (hits) => (0, readHonesty_1.readHonestyEnabled)()
+            ? {
+                readHonesty: (0, readHonesty_1.readHonestyForItems)({
+                    db, query, items: hits, ledgerRelPath: config_ledgerPath,
+                }),
+            }
+            : {};
+        try {
+            const retrieved = await (0, orchestrator_1.retrieveContext)(db, vectorIndex, provider, query, topK, priorityPaths, {}, { isLedgerNote: isLedger });
+            if (!productEvidenceEnabled || !productEvidenceOptions) {
+                // Preserve the pre-evidence response contract exactly when the feature is off.
+                const plain = (0, ledgerPresentation_1.presentLedgerEvents)(retrieved.hits, isLedger);
+                return void res.json({
+                    query: retrieved.query,
+                    hits: plain,
+                    ...(structuredOn
+                        ? { composedContext: (0, composer_1.composeQueryContextFromDb)(db, { query: retrieved.query, hits: plain }) }
+                        : {}),
+                    ...readHonesty(plain),
+                });
+            }
+            const attached = await (0, attach_1.attachSearchEvidence)({
+                query,
+                hits: retrieved.hits,
+                vaultPath,
+                options: productEvidenceOptions,
+                extractor: productEvidenceExtractor,
+                enabled: true,
+            });
+            // The evidence pass read the sources as stored; what the caller is shown is what the user said.
+            const shown = (0, ledgerPresentation_1.presentLedgerEvents)(attached.hits, isLedger);
+            res.json({
+                query: retrieved.query,
+                hits: shown,
+                evidence: attached.evidence,
+                ...(structuredOn
+                    ? { composedContext: (0, composer_1.composeQueryContextFromDb)(db, { query: retrieved.query, hits: shown.filter((h) => h.notePath !== attach_1.EVIDENCE_HIT_PATH), evidence: attached.evidence }) }
+                    : {}),
+                ...readHonesty(shown),
+            });
+        }
+        catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+    app.get('/entity/:name', (req, res) => {
+        const entity = (0, entityLookup_1.lookupEntity)(db, req.params.name);
+        if (!entity)
+            return void res.status(404).json({ error: 'not found' });
+        res.json(entity);
+    });
+    app.get('/facts/:entityId', (req, res) => {
+        // Current-only by default (temporal-memory contract): superseded facts carry
+        // valid_to and are opt-in via history/asOf endpoints, never the ID route.
+        const rows = db.prepare('SELECT * FROM facts WHERE subject_entity_id = ? AND valid_to IS NULL ORDER BY updated_at DESC').all(Number(req.params.entityId));
+        res.json(rows);
+    });
+    app.post('/memory/daily', async (req, res) => {
+        const { date, text, source = 'api' } = req.body;
+        if (!date || !text)
+            return void res.status(400).json({ error: 'date and text required' });
+        try {
+            await (0, writer_1.appendDailyMemory)(vaultPath, date, { text, source }, memoryDir);
+            res.json({ ok: true });
+        }
+        catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+    // Lifecycle-backed durable memory (ledger-first, supersedes, idempotent, returns receipt).
+    app.post('/memory/fact', async (req, res) => {
+        const { subject, predicate, object, source } = req.body;
+        if (!subject || !predicate || !object)
+            return void res.status(400).json({ error: 'subject, predicate, object required' });
+        try {
+            res.json(await (0, lifecycle_1.remember)(db, vaultPath, config_ledgerPath, { subject, predicate, object, source }));
+        }
+        catch (e) {
+            // A rejected lifecycle FIELD is the caller's mistake, not an engine fault: remember()
+            // validates every field before touching the ledger, so this is a bad request and must
+            // answer 4xx. Answering 500 made a client-side type bug (a non-string `object`) look like
+            // a server outage. Engine faults — unreadable ledger, reused event id, clock regression,
+            // an escaping ledger path — still throw plain Errors and stay 500.
+            if (e instanceof lifecycle_1.LifecycleInputError)
+                return void res.status(400).json({ error: e.message });
+            res.status(500).json({ error: e.message });
+        }
+    });
+    // Facts by entity NAME (agents don't know DB ids). ?asOf=ISO&history=1
+    app.get('/facts-for/:name', (req, res) => {
+        try {
+            res.json((0, lifecycle_1.factsFor)(db, req.params.name, {
+                asOf: req.query.asOf,
+                includeHistory: req.query.history === '1' || req.query.history === 'true',
+            }));
+        }
+        catch (e) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+    // One generic answer for anything a route did not handle: Express's own error page names the absolute path of the
+    // file that threw. The cause stays in this process's log.
+    app.use((err, _req, res, next) => {
+        if (res.headersSent)
+            return next(err);
+        const status = Number.isInteger(err?.status) && err.status >= 400 && err.status < 500 ? err.status : 500;
+        if (status >= 500)
+            console.error('[serve] request failed:', err);
+        res.status(status).json({ error: status >= 500 ? 'internal error' : 'bad request' });
+    });
+    return app;
+}

package/dist/buildIdentity.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILD_MANIFEST_PATH = exports.MAX_BUILD_MANIFEST_BYTES = void 0;
+exports.readBuildIdentity = readBuildIdentity;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const UNKNOWN_BUILD_IDENTITY = Object.freeze({
+    commit: 'unknown',
+    branch: 'unknown',
+    dirty: null,
+    builtAt: null,
+});
+/**
+ * Manifest size gate. A stamp written by scripts/ci/stamp-build.mjs is ~200
+ * bytes, so anything in the KiB range is not a build stamp this project wrote.
+ * Refusing it by size (before the contents are even parsed) bounds the work and
+ * the memory the reader can be forced into, and keeps a giant file from ever
+ * becoming the input to a response.
+ */
+exports.MAX_BUILD_MANIFEST_BYTES = 4096;
+/** A git revision id as printed by `git rev-parse HEAD`, shortened or full. */
+const COMMIT_PATTERN = /^[0-9a-fA-F]{7,40}$/;
+/**
+ * ISO-8601 instant: calendar date, time to the second, optional fractional
+ * seconds, and either `Z` or a numeric offset — the shapes `Date#toISOString`
+ * and ordinary ISO producers emit. Anything else (partial dates, prose,
+ * dates with embedded whitespace) is not a build timestamp.
+ */
+const BUILT_AT_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:\d{2})$/;
+/** Longest ISO instant worth accepting (offset + 6 fractional digits). */
+const MAX_BUILT_AT_LENGTH = 35;
+/** Git ref names are ASCII: letters, digits, `.`, `_`, `-` and `/` separators. */
+const BRANCH_PATTERN = /^[A-Za-z0-9._/-]+$/;
+/** git's own per-ref-component cap is 255 bytes; nothing legitimate is longer. */
+const MAX_BRANCH_LENGTH = 255;
+/** The engine package root: nearest ancestor of this module holding package.json. */
+function resolveEngineRoot() {
+    let dir = __dirname;
+    for (let up = 0; up < 3; up += 1) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(dir, 'package.json')))
+            return dir;
+        const parent = (0, node_path_1.dirname)(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Absolute path of the stamped manifest, or null when the package root cannot
+ * be located (then identity is simply unknown — never a guess).
+ *
+ * Resolved from the package root rather than a fixed relative hop because the
+ * two layouts differ: a compiled deployment loads this module from dist/ while
+ * a source run (tsx: `npm run mvp`, `renor serve`) loads it from src/, and both
+ * must find <engine>/dist/BUILD.json.
+ */
+exports.BUILD_MANIFEST_PATH = (() => {
+    const root = resolveEngineRoot();
+    return root === null ? null : (0, node_path_1.join)(root, 'dist', 'BUILD.json');
+})();
+/** Hex revision id, or the unknown placeholder. */
+function validatedCommit(value) {
+    return typeof value === 'string' && COMMIT_PATTERN.test(value)
+        ? value
+        : UNKNOWN_BUILD_IDENTITY.commit;
+}
+/**
+ * Plausible git ref name, or the unknown placeholder. Enforces the
+ * `git check-ref-format` rules a charset check alone would miss (`..`, `@{`,
+ * leading dot, `.lock` suffix, empty component), so a filesystem path, a tenant
+ * slug, a URL or a ref-shaped injection cannot pass as a branch.
+ */
+function validatedBranch(value) {
+    const unknown = UNKNOWN_BUILD_IDENTITY.branch;
+    if (typeof value !== 'string' || value.length > MAX_BRANCH_LENGTH)
+        return unknown;
+    if (!BRANCH_PATTERN.test(value))
+        return unknown;
+    if (value.includes('..') || value.includes('@{'))
+        return unknown;
+    for (const component of value.split('/')) {
+        if (component === '' || component.startsWith('.'))
+            return unknown;
+        if (component.endsWith('.lock'))
+            return unknown;
+    }
+    return value;
+}
+/** Parsable ISO-8601 instant, or null. */
+function validatedBuiltAt(value) {
+    if (typeof value !== 'string' || value.length > MAX_BUILT_AT_LENGTH)
+        return null;
+    if (!BUILT_AT_PATTERN.test(value))
+        return null;
+    return Number.isFinite(Date.parse(value)) ? value : null;
+}
+/**
+ * Reads the build manifest. Returns the unknown identity — never throws — when
+ * the manifest is absent, unreadable, oversized, not JSON, not an object, or
+ * carries a value that fails its field's shape check.
+ */
+function readBuildIdentity(manifestPath = exports.BUILD_MANIFEST_PATH) {
+    if (manifestPath === null)
+        return { ...UNKNOWN_BUILD_IDENTITY };
+    let raw;
+    try {
+        if ((0, node_fs_1.statSync)(manifestPath).size > exports.MAX_BUILD_MANIFEST_BYTES) {
+            return { ...UNKNOWN_BUILD_IDENTITY }; // not a stamp we wrote
+        }
+        raw = (0, node_fs_1.readFileSync)(manifestPath, 'utf8');
+    }
+    catch {
+        return { ...UNKNOWN_BUILD_IDENTITY }; // pre-stamp / snapshot deployment
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return { ...UNKNOWN_BUILD_IDENTITY };
+        }
+        const manifest = parsed;
+        return {
+            commit: validatedCommit(manifest.commit),
+            branch: validatedBranch(manifest.branch),
+            dirty: typeof manifest.dirty === 'boolean' ? manifest.dirty : null,
+            builtAt: validatedBuiltAt(manifest.builtAt),
+        };
+    }
+    catch {
+        return { ...UNKNOWN_BUILD_IDENTITY };
+    }
+}

package/dist/cli-extractors.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWritePathExtractors = buildWritePathExtractors;
+const openai_1 = __importDefault(require("openai"));
+const factExtractor_1 = require("./extraction/factExtractor");
+const extractionClient_1 = require("./extraction/extractionClient");
+const typedFacts_1 = require("./extraction/typedFacts");
+const eventExtractor_1 = require("./extraction/eventExtractor");
+const preferenceExtractor_1 = require("./extraction/preferenceExtractor");
+/**
+ * Structured-row lanes use only a named extractor provider. A bare
+ * OPENAI_API_KEY does not arm them. LLM_EXTRACTION is the older fact path:
+ * when that flag is on and no named provider exists, it keeps the OpenAI
+ * client main already built from that key.
+ *
+ * The legacy fact path asks for `FACTS_MODEL` only when the resolved provider is
+ * one of the extractor-specific providers. On the generic OPENAI_API_KEY +
+ * OPENAI_BASE_URL fallback it keeps the fact extractor's own `gpt-4o-mini`
+ * default, which is the model `main` sent there. See
+ * `isExtractorSpecificProvider`.
+ */
+function buildWritePathExtractors(config, env = process.env) {
+    const resolved = (0, extractionClient_1.openExtractorClient)(typedFacts_1.FACTS_MODEL, env);
+    const extractorClient = resolved?.client ?? null;
+    const legacyFactClient = config.llmExtraction && !extractorClient && config.openaiApiKey
+        ? new openai_1.default({ apiKey: config.openaiApiKey })
+        : null;
+    const factClient = (extractorClient ?? legacyFactClient);
+    return {
+        factExtractor: config.llmExtraction && factClient
+            ? (title, body) => (0, factExtractor_1.extractFacts)(factClient, title, body, (0, extractionClient_1.isExtractorSpecificProvider)(resolved?.config ?? null) ? typedFacts_1.FACTS_MODEL : 'gpt-4o-mini')
+            : undefined,
+        numericFactExtractor: (0, typedFacts_1.typedFactsEnabled)(env) && extractorClient
+            ? (title, body) => (0, typedFacts_1.extractNumericFacts)(extractorClient, title, body)
+            : undefined,
+        eventExtractor: (0, eventExtractor_1.chronicleEnabled)(env) && extractorClient
+            ? (title, body) => (0, eventExtractor_1.extractEvents)(extractorClient, title, body)
+            : undefined,
+        preferenceExtractor: (0, preferenceExtractor_1.prefsEnabled)(env) && extractorClient
+            ? (title, body) => (0, preferenceExtractor_1.extractPreferences)(extractorClient, title, body)
+            : undefined,
+    };
+}