@rulvar/core 1.36.0 → 1.38.0

package/dist/index.d.ts

@@ -6469,9 +6469,16 @@ declare class JsonlFileStore implements MetaLookupStore {
 /**
 * File-backed TranscriptStore (M6-T02): blobs (transcripts, checkpoints,
 * persisted CompiledWorkflow sources) as one file per ref under `dir`,
-* so compiled runs resume across processes. Refs follow
-* the `<runId>/<name>` convention; each path segment is checked
-* filesystem-safe and nested segments become directories.
+* so compiled runs resume across processes. Refs follow the
+* `<runId>/<name>` convention; nested segments become directories.
+*
+* Every ref is contained under `dir` (v1.36.0 review SEC-P1): each
+* segment must match `[A-Za-z0-9._-]` and be neither empty, '.', nor
+* '..', and the resolved path must stay under the resolved root. A '..'
+* segment used to pass the per-segment alphabet (dots are in it) and, via
+* `join`, escape the root; a caller passing an untrusted ref (or an
+* untrusted runId, which prefixes checkpoint and workflow-source refs)
+* could read, write, or delete `.bin` files outside `dir`.
 */
 declare class FileTranscriptStore implements TranscriptStore {
   private readonly dir;

package/dist/index.js

@@ -1,6 +1,6 @@
 import { createHash, getRandomValues, randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -2302,6 +2302,79 @@ function applyClaimOps(claims, ops) {
 	}
 	return next;
 }
+/** A lowercase sha256 digest: 64 hex characters. */
+const HASH_PATTERN = /^[0-9a-f]{64}$/;
+const CLAIM_STATUSES = /* @__PURE__ */ new Set([
+	"active",
+	"stale",
+	"superseded",
+	"archived"
+]);
+/**
+* Structural issues of one PERSISTED claim (empty = sound). Distinct from
+* the editorial commit validator (claims.ts): a persisted snapshot
+* legitimately holds non-active statuses (stale, superseded, archived) and
+* carries no gate, so only shape and vocabulary are checked here. This is
+* the boundary that keeps a null or partial claim from reaching the card
+* render, where `claim.status` would throw an untyped TypeError (v1.36.0
+* review P2-6).
+*/
+function persistedClaimIssues(value, path) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return [`${path}: expected a claim object`];
+	const claim = value;
+	const issues = [];
+	if (typeof claim.id !== "string" || claim.id.length === 0) issues.push(`${path}.id: expected a non-empty string`);
+	const subject = claim.subject;
+	if (subject === null || typeof subject !== "object") issues.push(`${path}.subject: expected an object`);
+	else if (typeof subject.model !== "string" || !subject.model.includes(":")) issues.push(`${path}.subject.model: expected a 'provider:model' string`);
+	if (typeof claim.taskClass !== "string" || claim.taskClass.length === 0) issues.push(`${path}.taskClass: expected a non-empty string`);
+	if (claim.polarity !== "strength" && claim.polarity !== "weakness") issues.push(`${path}.polarity: expected 'strength' or 'weakness'`);
+	if (typeof claim.statement !== "string" || claim.statement.length === 0) issues.push(`${path}.statement: expected a non-empty string`);
+	if (claim.class !== "eval-measured" && claim.class !== "human-editorial") issues.push(`${path}.class: expected 'eval-measured' or 'human-editorial'`);
+	if (typeof claim.status !== "string" || !CLAIM_STATUSES.has(claim.status)) issues.push(`${path}.status: expected active, stale, superseded, or archived`);
+	if (!Array.isArray(claim.evidence) || claim.evidence.length === 0) issues.push(`${path}.evidence: expected a non-empty array`);
+	if (claim.confidence !== "high" && claim.confidence !== "medium" && claim.confidence !== "low") issues.push(`${path}.confidence: expected 'high', 'medium', or 'low'`);
+	if (typeof claim.observedAt !== "string" || Number.isNaN(Date.parse(claim.observedAt))) issues.push(`${path}.observedAt: expected an ISO date`);
+	if (typeof claim.expiresAt !== "string" || Number.isNaN(Date.parse(claim.expiresAt))) issues.push(`${path}.expiresAt: expected an ISO date`);
+	const author = claim.author;
+	if (author === null || typeof author !== "object") issues.push(`${path}.author: expected an object`);
+	else {
+		if (author.kind !== "eval-pipeline" && author.kind !== "human") issues.push(`${path}.author.kind: expected 'eval-pipeline' or 'human'`);
+		if (typeof author.id !== "string" || author.id.length === 0) issues.push(`${path}.author.id: expected a non-empty string`);
+	}
+	return issues;
+}
+/**
+* The single read boundary of the store (v1.36.0 review P2-6). A persisted
+* snapshot must hold a nonnegative integer version, a lowercase sha256
+* hash, structurally sound claims, and a hash that MATCHES its claims: the
+* KnowledgeSnapshot contract promises the hash is the deterministic
+* content hash of the claims, so a file edited without rehashing (a forged
+* version or hash, a torn write) is refused with a typed ConfigError
+* instead of flowing on to forge the audit trail or crash the render.
+*/
+function validateKnowledgeSnapshot(parsed, path) {
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new ConfigError(`knowledge store file does not hold a KnowledgeSnapshot: ${path}`);
+	const snapshot = parsed;
+	const issues = [];
+	const version = snapshot.version;
+	if (typeof version !== "number" || !Number.isInteger(version) || version < 0) issues.push(`version: expected a nonnegative integer; got ${String(version)}`);
+	const hash = snapshot.hash;
+	if (typeof hash !== "string" || !HASH_PATTERN.test(hash)) issues.push("hash: expected a lowercase sha256 digest of 64 hex characters");
+	if (!Array.isArray(snapshot.claims)) issues.push("claims: expected an array");
+	else snapshot.claims.forEach((claim, index) => {
+		issues.push(...persistedClaimIssues(claim, `claims[${String(index)}]`));
+	});
+	if (issues.length > 0) throw new ConfigError(`knowledge store file is not a valid KnowledgeSnapshot (${path}):\n- ${issues.join("\n- ")}`);
+	const claims = snapshot.claims;
+	const recomputed = knowledgeHash(claims);
+	if (hash !== recomputed) throw new ConfigError(`knowledge store hash does not match its claims (${path}): stored ${String(hash)}, computed ${recomputed}; the file was edited without rehashing`);
+	return {
+		version,
+		hash,
+		claims
+	};
+}
 var FileModelKnowledgeStore = class {
 	path;
 	activeClaimsCap;
@@ -2330,13 +2403,7 @@ var FileModelKnowledgeStore = class {
 		} catch (cause) {
 			throw new ConfigError(`knowledge store file is not valid JSON: ${this.path}`, { cause });
 		}
-		const snapshot = parsed;
-		if (snapshot === null || typeof snapshot.version !== "number" || typeof snapshot.hash !== "string" || !Array.isArray(snapshot.claims)) throw new ConfigError(`knowledge store file does not hold a KnowledgeSnapshot: ${this.path}`);
-		return {
-			version: snapshot.version,
-			hash: snapshot.hash,
-			claims: snapshot.claims
-		};
+		return validateKnowledgeSnapshot(parsed, this.path);
 	}
 	async current() {
 		return this.read();
@@ -6578,9 +6645,16 @@ const TRANSCRIPT_SUFFIX = ".bin";
 /**
 * File-backed TranscriptStore (M6-T02): blobs (transcripts, checkpoints,
 * persisted CompiledWorkflow sources) as one file per ref under `dir`,
-* so compiled runs resume across processes. Refs follow
-* the `<runId>/<name>` convention; each path segment is checked
-* filesystem-safe and nested segments become directories.
+* so compiled runs resume across processes. Refs follow the
+* `<runId>/<name>` convention; nested segments become directories.
+*
+* Every ref is contained under `dir` (v1.36.0 review SEC-P1): each
+* segment must match `[A-Za-z0-9._-]` and be neither empty, '.', nor
+* '..', and the resolved path must stay under the resolved root. A '..'
+* segment used to pass the per-segment alphabet (dots are in it) and, via
+* `join`, escape the root; a caller passing an untrusted ref (or an
+* untrusted runId, which prefixes checkpoint and workflow-source refs)
+* could read, write, or delete `.bin` files outside `dir`.
 */
 var FileTranscriptStore = class {
 	dir;
@@ -6590,9 +6664,13 @@ var FileTranscriptStore = class {
 	}
 	blobPath(ref) {
 		const segments = ref.split("/");
-		for (const segment of segments) if (!/^[A-Za-z0-9._-]+$/.test(segment)) throw new JournalOrderViolation(`FileTranscriptStore: ref segment '${segment}' is not filesystem-safe`);
+		for (const segment of segments) if (segment === "" || segment === "." || segment === ".." || !/^[A-Za-z0-9._-]+$/.test(segment)) throw new JournalOrderViolation(`FileTranscriptStore: ref segment '${segment}' is not filesystem-safe`);
 		const name = segments.pop() ?? "";
-		return join(this.dir, ...segments, `${name}${TRANSCRIPT_SUFFIX}`);
+		const path = join(this.dir, ...segments, `${name}${TRANSCRIPT_SUFFIX}`);
+		const root = resolve(this.dir);
+		const resolved = resolve(path);
+		if (resolved !== root && !resolved.startsWith(`${root}${sep}`)) throw new JournalOrderViolation(`FileTranscriptStore: ref '${ref}' resolves outside the configured root`);
+		return path;
 	}
 	async put(ref, blob) {
 		const path = this.blobPath(ref);
@@ -6610,6 +6688,7 @@ var FileTranscriptStore = class {
 		}
 	}
 	async list(runId) {
+		if (runId === "." || runId === "..") throw new JournalOrderViolation(`FileTranscriptStore: runId '${runId}' is not filesystem-safe`);
 		const root = join(this.dir, safeName(runId));
 		const refs = [];
 		const walk = (dir, prefix) => {
@@ -13525,6 +13604,29 @@ var EventBus = class {
 	}
 };
 //#endregion
+//#region src/l0/run-id.ts
+/**
+* Run id containment (v1.36.0 review SEC-P1). A runId becomes both a
+* journal path component (JsonlFileStore.safeName) and the PREFIX of every
+* transcript ref (checkpointRefFor, workflowSourceRef append `/...`). The
+* journal's whole-token regex rejects a separator, but a bare '.' or '..'
+* slips through as a single component there and, once a '/suffix' is
+* appended, becomes a real traversal segment at the transcript store. The
+* engine validates the runId at its boundary, before the first transcript
+* write, so an untrusted runId is refused with a typed ConfigError instead
+* of escaping the configured transcript root.
+*/
+/** Filesystem-safe token: the journal store's own alphabet. */
+const SAFE_RUN_ID = /^[A-Za-z0-9._-]+$/;
+/**
+* Throws a ConfigError unless runId is a filesystem-safe token: a
+* non-empty string over [A-Za-z0-9._-] that is neither '.' nor '..'. The
+* dot pair passes the alphabet on its own, so it is refused explicitly.
+*/
+function assertSafeRunId(runId, context) {
+	if (typeof runId !== "string" || runId === "" || runId === "." || runId === ".." || !SAFE_RUN_ID.test(runId)) throw new ConfigError(`${context}: runId ${JSON.stringify(runId)} is not filesystem-safe (allowed: [A-Za-z0-9._-], and neither "." nor "..")`);
+}
+//#endregion
 //#region src/runner/inprocess.ts
 /**
 * ScriptRunner SPI and InProcessRunner (M1-T11).
@@ -13751,6 +13853,7 @@ function createEngine(options) {
 		const compiled = wf.kind === "compiled-workflow" ? wf : void 0;
 		if (compiled !== void 0 && options.runners?.sandbox === void 0) throw new ConfigError("running a CompiledWorkflow requires a sandbox runner: pass createEngine({ runners: { sandbox: new WorkerSandboxRunner() } }) from @rulvar/planner ");
 		const runId = resumeCtx?.runId ?? opts?.runId ?? mintRunId();
+		assertSafeRunId(runId, "engine.run");
 		const registry = buildDeriverRegistry(options.extraDerivers);
 		const segmentsBefore = resumeCtx?.segmentsBefore ?? 0;
 		const telemetryBase = segmentsBefore * EVENT_SEGMENT_STRIDE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",