@panaversity/ksor 0.0.49 → 0.0.50

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @panaversity/ksor
 
+## 0.0.50
+
+### Patch Changes
+
+- f27f947: The three embed tuning variables now take effect when set in `.env`.
+  `KSOR_EMBED_TIMEOUT_S`, `KSOR_QUERY_EMBED_TIMEOUT_S` and `KSOR_EMBED_CACHE_MAX`
+  were read once at module load — before the CLI applies `.env` in `main()` — so
+  a value set there was silently ignored and the default stood. An adopter who
+  set `KSOR_EMBED_CACHE_MAX` to fit a small runtime, for instance, still got the
+  ~250 MB default cache and could OOM in production with nothing pointing at why.
+  The reads now happen at use. Exported shell variables were unaffected and still
+  are.
+
 ## 0.0.49
 
 ### Patch Changes

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-dqpI-p1a.mjs";
-import { A as parseViewer, B as tlsPosture, C as contentPoolMin, D as outlineHandler, E as keyRingFromEnv, F as runProbe$1, H as withPgRetry$1, I as searchHandler, L as servingPolicy$1, M as prewarmPool, N as readHandler, O as parseInstanceText$1, P as recordIsUndescribed, R as storedTextSearchConfig, S as contentPool$1, T as instancePathOf$1, U as withProbeDeadline$1, V as validateViewer, W as z$1, _ as assertGovernanceServable$1, a as GovernanceGateError$1, b as checkEmbeddingSpace$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, g as TextSearchConfigMismatch, h as TRUST_TIERS$1, i as FLOOR, j as pooledEndpointFor, k as parseTrustFloor, l as MissingProviderKeyError$1, m as SchemaVersionError, n as ContentStoreError$1, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, r as EmbeddingSpaceMismatch$1, t as AudienceError$1, u as OUTLINE_OUTPUT, v as assertSchemaCompatible, w as embedQueryVlit, x as composeInstructions, y as buildShippedProvider$1, z as tallyHandlers } from "./gateway-api-8DkVCYYi-Bo0_Y1Y3.mjs";
+import { A as parseViewer, B as tlsPosture, C as contentPoolMin, D as outlineHandler, E as keyRingFromEnv, F as runProbe$1, H as withPgRetry$1, I as searchHandler, L as servingPolicy$1, M as prewarmPool, N as readHandler, O as parseInstanceText$1, P as recordIsUndescribed, R as storedTextSearchConfig, S as contentPool$1, T as instancePathOf$1, U as withProbeDeadline$1, V as validateViewer, W as z$1, _ as assertGovernanceServable$1, a as GovernanceGateError$1, b as checkEmbeddingSpace$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, g as TextSearchConfigMismatch, h as TRUST_TIERS$1, i as FLOOR, j as pooledEndpointFor, k as parseTrustFloor, l as MissingProviderKeyError$1, m as SchemaVersionError, n as ContentStoreError$1, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, r as EmbeddingSpaceMismatch$1, t as AudienceError$1, u as OUTLINE_OUTPUT, v as assertSchemaCompatible, w as embedQueryVlit, x as composeInstructions, y as buildShippedProvider$1, z as tallyHandlers } from "./gateway-api-D8HlLys2-Ca8OnwLn.mjs";
 import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { InMemoryTransport, LATEST_PROTOCOL_VERSION, createMcpHandler } from "@modelcontextprotocol/server";
@@ -17,7 +17,7 @@ import { Document, YAMLParseError, isCollection, isMap, isPair, isSeq, parseAllD
 import { parseArgs } from "node:util";
 import { readFile } from "node:fs/promises";
 import { execFileSync, spawnSync } from "node:child_process";
-//#region ../content-gateway/dist/main-BXNvtHqd.mjs
+//#region ../content-gateway/dist/main-DMCMO8ye.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -4709,7 +4709,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-C3D7buZN.mjs
+//#region ../content/dist/commands-BNxmBRjs.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -5787,11 +5787,12 @@ async function topOneScore(client, scope, queryVector) {
 	})).rows[0]?.[0];
 	return raw === void 0 || raw === null ? null : toNumber(raw, "score");
 }
-const EMBED_TIMEOUT_S = envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
+/** The per-request HTTP timeout for a document (ingest/batch) embed. */
+const EMBED_TIMEOUT_S = () => envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
 /** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. Note: query-embed.ts reads the
 * SAME variable with a different default (5.0) as its hard wall clock — two
 * deliberate reads, carried from the oracle (embedding.py:62 vs query_embed.py:44). */
-const QUERY_EMBED_TIMEOUT_S = envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
+const QUERY_EMBED_TIMEOUT_S = () => envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
 /** The text we embed for a chunk: the readable hierarchical heading path, then the content. */
 function embedInput(title, headingPath, content) {
 	const path = headingPath ? (title ? title + " > " : "") + headingPath.replaceAll("/", " > ").replaceAll("-", " ").trim() : title;
@@ -6213,8 +6214,8 @@ function buildShippedProvider(name, opts) {
 		dim: opts.dim ?? 1536,
 		documentTaskLabel: EMBED_TASK_DOCUMENT,
 		queryTaskLabel: EMBED_TASK_QUERY,
-		documentTimeoutS: EMBED_TIMEOUT_S,
-		queryTimeoutS: QUERY_EMBED_TIMEOUT_S
+		documentTimeoutS: EMBED_TIMEOUT_S(),
+		queryTimeoutS: QUERY_EMBED_TIMEOUT_S()
 	});
 }
 /** Written to yield ZERO ROWS, never an error, when the schema is absent. */

package/dist/{gateway-api-8DkVCYYi-Bo0_Y1Y3.mjs → gateway-api-D8HlLys2-Ca8OnwLn.mjs}

@@ -6,7 +6,7 @@ import { z, z as z$1 } from "zod";
 import path, { join } from "node:path";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import pg from "pg";
-//#region ../content-gateway/dist/gateway-api-8DkVCYYi.mjs
+//#region ../content-gateway/dist/gateway-api-D8HlLys2.mjs
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 /**
@@ -8769,11 +8769,12 @@ function validate$1(ring, token, scope, nowMs = Date.now()) {
 		reason: null
 	};
 }
-const EMBED_TIMEOUT_S = envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
+/** The per-request HTTP timeout for a document (ingest/batch) embed. */
+const EMBED_TIMEOUT_S = () => envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
 /** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. Note: query-embed.ts reads the
 * SAME variable with a different default (5.0) as its hard wall clock — two
 * deliberate reads, carried from the oracle (embedding.py:62 vs query_embed.py:44). */
-const QUERY_EMBED_TIMEOUT_S = envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
+const QUERY_EMBED_TIMEOUT_S = () => envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
 function l2Normalize(v) {
 	const norm = Math.sqrt(v.reduce((acc, x) => acc + x * x, 0));
 	return norm === 0 ? v : v.map((x) => x / norm);
@@ -9120,8 +9121,8 @@ function buildShippedProvider(name, opts) {
 		dim: opts.dim ?? 1536,
 		documentTaskLabel: EMBED_TASK_DOCUMENT,
 		queryTaskLabel: EMBED_TASK_QUERY,
-		documentTimeoutS: EMBED_TIMEOUT_S,
-		queryTimeoutS: QUERY_EMBED_TIMEOUT_S
+		documentTimeoutS: EMBED_TIMEOUT_S(),
+		queryTimeoutS: QUERY_EMBED_TIMEOUT_S()
 	});
 }
 /** Written to yield ZERO ROWS, never an error, when the schema is absent. */
@@ -9991,9 +9992,46 @@ async function outline(client, scope, options = {}) {
 		generation: pinned ?? rows[0]?.generation ?? null
 	};
 }
-let cacheMax = envInt("KSOR_EMBED_CACHE_MAX", 1e4, 1);
-/** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. */
-const EMBED_WALL_TIMEOUT_S = envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 5, .1);
+/**
+* Query-embedding cache, converted from the oracle (sor-agentfactory @
+* b554f91, sor_content/lib/query_embed.py): L1 in-process LRU + SINGLE-FLIGHT
+* (concurrent identical misses share ONE paid embed), keyed with
+* model + task + dim so a model or dimension bump can never serve a stale
+* vector. Whitespace collapses; case does NOT fold (folding would change the
+* embedded text).
+*
+* A tiny CIRCUIT BREAKER guards the provider: after an embed failure, further
+* misses raise immediately for a short cooldown (cache hits still serve) —
+* during an outage every request degrades to keyword-only instantly instead
+* of each unique query paying its own failed attempt against a provider that
+* is already down. The breaker is keyed per SPACE (modelId, dim), like the
+* keys: a failing provider A must not degrade a healthy provider B.
+*
+* Conversion notes (decision 6):
+* - The oracle's optional Redis L2 (fail-open both directions, TTL
+*   SOR_EMBED_CACHE_TTL, the `sor:emb:*` key scheme) is DROPPED — it was
+*   multi-instance infrastructure; the L1 + single-flight carry a
+*   single-process deployment. It returns, if ever, with real multi-instance
+*   serving — nothing here forecloses it.
+* - The oracle's waiter-shield (`asyncio.shield`) and owner-cancel handling
+*   protected the shared future from one caller's cancellation. JS promises
+*   are not cancellable, so sharing the promise IS the whole mechanism: no
+*   caller can cancel another, and there is no owner-cancelled path to map.
+* - `asyncio.wait_for` CANCELLED the embed on timeout; a JS promise cannot be
+*   cancelled, so on timeout the losing call is abandoned (its settlement is
+*   still observed, so it can never surface as an unhandled rejection) and
+*   runs out its own HTTP timeout in the background.
+* - The breaker clock is Date.now() (ms) rather than a monotonic clock — the
+*   10 s cooldown is coarse, and fake-timer tests need the system clock.
+*/
+/** Oracle env var: SOR_EMBED_CACHE_MAX. */
+let memoizedCacheMax;
+function currentCacheMax() {
+	return memoizedCacheMax ??= envInt("KSOR_EMBED_CACHE_MAX", 1e4, 1);
+}
+/** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. Read at use, not at module load
+* — see the cache-max note above. */
+const EMBED_WALL_TIMEOUT_S = () => envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 5, .1);
 const cache = /* @__PURE__ */ new Map();
 const inflight = /* @__PURE__ */ new Map();
 const breakerOpenUntilByMs = /* @__PURE__ */ new Map();
@@ -10037,10 +10075,11 @@ function breakerOpenUntil(provider) {
 	return breakerOpenUntilByMs.get(spaceKey(provider)) ?? 0;
 }
 function withWallClock(work) {
+	const wallTimeoutS = EMBED_WALL_TIMEOUT_S();
 	return new Promise((resolve, reject) => {
 		const timer = setTimeout(() => {
-			reject(new QueryEmbedTimeoutError(`query embed exceeded the ${EMBED_WALL_TIMEOUT_S}s wall clock — treated as a provider failure (degrade to keyword-only)`));
-		}, EMBED_WALL_TIMEOUT_S * 1e3);
+			reject(new QueryEmbedTimeoutError(`query embed exceeded the ${wallTimeoutS}s wall clock — treated as a provider failure (degrade to keyword-only)`));
+		}, wallTimeoutS * 1e3);
 		work.then((value) => {
 			clearTimeout(timer);
 			resolve(value);
@@ -10061,7 +10100,7 @@ async function embedMiss(normalized, key, provider) {
 		const literal = vlit(vec);
 		cache.delete(key);
 		cache.set(key, literal);
-		while (cache.size > cacheMax) {
+		while (cache.size > currentCacheMax()) {
 			const oldest = cache.keys().next().value;
 			if (oldest === void 0) break;
 			cache.delete(oldest);

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { D as outlineHandler, I as searchHandler, N as readHandler, P as recordIsUndescribed, W as z$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, h as TRUST_TIERS, i as FLOOR, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, s as MAX_SEARCH_K, u as OUTLINE_OUTPUT, x as composeInstructions } from "./gateway-api-8DkVCYYi-Bo0_Y1Y3.mjs";
+import { D as outlineHandler, I as searchHandler, N as readHandler, P as recordIsUndescribed, W as z$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, h as TRUST_TIERS, i as FLOOR, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, s as MAX_SEARCH_K, u as OUTLINE_OUTPUT, x as composeInstructions } from "./gateway-api-D8HlLys2-Ca8OnwLn.mjs";
 export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, TRUST_TIERS, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",