@rivus/platform 0.16.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PerfectPan
+
+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

@@ -0,0 +1,5 @@
+# @rivus/platform
+
+Shared filesystem, persistence, identity, and concurrency primitives used by Rivus runtime packages.
+
+The package intentionally exposes named capability subpaths. It does not expose a business or domain root.

package/dist/concurrency/index.d.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+
+//#region src/concurrency/serial-executor.d.ts
+interface SerialExecutor {
+  run<T>(operation: () => Promise<T>): Promise<T>;
+}
+declare function createSerialExecutor(): SerialExecutor;
+//#endregion
+//#region src/concurrency/periodic-effect-loop.d.ts
+interface PeriodicEffectLoopOptions {
+  readonly intervalMs: number;
+  readonly onError?: (error: unknown) => void | Promise<void>;
+  readonly run: () => Effect.Effect<unknown, unknown>;
+  readonly sleep: (ms: number) => Effect.Effect<void, unknown>;
+}
+interface PeriodicEffectLoop {
+  running(): boolean;
+  start(): void;
+  stop(): Promise<void>;
+}
+declare function createEffectLoopDriver(loop: Effect.Effect<unknown, never>): PeriodicEffectLoop;
+declare function createPeriodicEffectLoop(options: PeriodicEffectLoopOptions): PeriodicEffectLoop;
+//#endregion
+export { type PeriodicEffectLoop, type PeriodicEffectLoopOptions, type SerialExecutor, createEffectLoopDriver, createPeriodicEffectLoop, createSerialExecutor };

package/dist/concurrency/index.js

@@ -0,0 +1,41 @@
+import { Effect, Fiber } from "effect";
+//#region src/concurrency/serial-executor.ts
+function createSerialExecutor() {
+	let tail = Promise.resolve();
+	return { run: (operation) => {
+		const result = tail.then(operation, operation);
+		tail = result.then(() => void 0, () => void 0);
+		return result;
+	} };
+}
+//#endregion
+//#region src/concurrency/periodic-effect-loop.ts
+function createEffectLoopDriver(loop) {
+	let running = false;
+	let fiber;
+	return {
+		running: () => running,
+		start: () => {
+			if (running) return;
+			running = true;
+			fiber = Effect.runFork(loop);
+		},
+		stop: async () => {
+			running = false;
+			const activeFiber = fiber;
+			fiber = void 0;
+			if (activeFiber) await Effect.runPromise(Fiber.interrupt(activeFiber));
+		}
+	};
+}
+function createPeriodicEffectLoop(options) {
+	const reportError = (error) => {
+		const reported = options.onError?.(error);
+		return reported instanceof Promise ? Effect.promise(() => reported) : Effect.void;
+	};
+	const continueAfterReporting = (effect) => effect.pipe(Effect.asVoid, Effect.catchAll((error) => reportError(error)));
+	const cycle = Effect.suspend(() => continueAfterReporting(options.run()).pipe(Effect.flatMap(() => continueAfterReporting(options.sleep(options.intervalMs))), Effect.flatMap(() => cycle)));
+	return createEffectLoopDriver(cycle);
+}
+//#endregion
+export { createEffectLoopDriver, createPeriodicEffectLoop, createSerialExecutor };

package/dist/filesystem/index.d.ts

@@ -0,0 +1,5 @@
+//#region src/filesystem/path-boundary.d.ts
+declare function isPathWithin(root: string, candidate: string): boolean;
+declare function assertPathWithin(root: string, candidate: string, message: string): void;
+//#endregion
+export { assertPathWithin, isPathWithin };

package/dist/filesystem/index.js

@@ -0,0 +1,11 @@
+import { isAbsolute, relative, sep } from "node:path";
+//#region src/filesystem/path-boundary.ts
+function isPathWithin(root, candidate) {
+	const child = relative(root, candidate);
+	return child === "" || !child.startsWith(`..${sep}`) && child !== ".." && !isAbsolute(child);
+}
+function assertPathWithin(root, candidate, message) {
+	if (!isPathWithin(root, candidate)) throw new Error(message);
+}
+//#endregion
+export { assertPathWithin, isPathWithin };

package/dist/identity/index.d.ts

@@ -0,0 +1,10 @@
+//#region src/identity/stable-id.d.ts
+declare function createStableId(prefix: string, value: unknown): string;
+//#endregion
+//#region src/identity/random-id.d.ts
+declare function createRandomId(): string;
+//#endregion
+//#region src/identity/sha256-digest.d.ts
+declare function createSha256Digest(value: string): string;
+//#endregion
+export { createRandomId, createSha256Digest, createStableId };

package/dist/identity/index.js

@@ -0,0 +1,17 @@
+import { createHash, randomUUID } from "node:crypto";
+//#region src/identity/stable-id.ts
+function createStableId(prefix, value) {
+	return `${prefix}:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+//#endregion
+//#region src/identity/random-id.ts
+function createRandomId() {
+	return randomUUID();
+}
+//#endregion
+//#region src/identity/sha256-digest.ts
+function createSha256Digest(value) {
+	return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+//#endregion
+export { createRandomId, createSha256Digest, createStableId };

package/dist/persistence/index.d.ts

@@ -0,0 +1,38 @@
+//#region src/persistence/persistence-value.d.ts
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+declare function isNodeErrorWithCode(error: unknown, code: string): error is NodeJS.ErrnoException;
+//#endregion
+//#region src/persistence/jsonl/jsonl-snapshot-store.d.ts
+declare class JsonlSnapshotStoreCorrupted extends Error {
+  readonly name = "JsonlSnapshotStoreCorrupted";
+}
+interface LoadJsonlSnapshotStoreOptions<T> {
+  readonly compactThreshold: number;
+  readonly errorLabel: string;
+  readonly filePath: string;
+  readonly isRecord: (value: unknown) => value is T;
+  readonly keyOf: (record: T) => string;
+  readonly validateSequence: (previous: T | undefined, record: T, lineNumber: number) => string | undefined;
+  readonly version: number;
+}
+declare function loadJsonlSnapshotStore<T>(options: LoadJsonlSnapshotStoreOptions<T>): Promise<ReadonlyArray<T>>;
+declare function appendJsonlRecord<T>(filePath: string, version: number, record: T): Promise<void>;
+declare function writeJsonlSnapshot<T>(filePath: string, version: number, records: ReadonlyArray<T>): Promise<void>;
+//#endregion
+//#region src/persistence/files/read-persistence-file.d.ts
+declare function readPersistenceFile(filePath: string): Promise<string | undefined>;
+//#endregion
+//#region src/persistence/files/write-persistence-file.d.ts
+declare function writePersistenceFile(filePath: string, value: unknown): Promise<void>;
+//#endregion
+//#region src/persistence/files/write-atomic-text-file.d.ts
+interface WriteAtomicTextFileOptions {
+  /** Mode for a newly created destination. Existing destination mode wins. */
+  readonly mode?: number;
+  /** Flush the temporary file and its parent directory before returning. */
+  readonly durable?: boolean;
+}
+/** Replace one UTF-8 text file through a same-directory temporary file. */
+declare function writeAtomicTextFile(filePath: string, contents: string, options?: WriteAtomicTextFileOptions): Promise<void>;
+//#endregion
+export { JsonlSnapshotStoreCorrupted, type LoadJsonlSnapshotStoreOptions, type WriteAtomicTextFileOptions, appendJsonlRecord, isNodeErrorWithCode, isRecord, loadJsonlSnapshotStore, readPersistenceFile, writeAtomicTextFile, writeJsonlSnapshot, writePersistenceFile };

package/dist/persistence/index.js

@@ -0,0 +1,140 @@
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, open, readFile, rename, stat, truncate, unlink, writeFile } from "node:fs/promises";
+//#region src/persistence/persistence-value.ts
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isNodeErrorWithCode(error, code) {
+	return error instanceof Error && "code" in error && error.code === code;
+}
+//#endregion
+//#region src/persistence/files/read-persistence-file.ts
+async function readPersistenceFile(filePath) {
+	try {
+		return await readFile(filePath, "utf8");
+	} catch (error) {
+		if (isNodeErrorWithCode(error, "ENOENT")) return void 0;
+		throw error;
+	}
+}
+//#endregion
+//#region src/persistence/jsonl/jsonl-snapshot-store.ts
+var JsonlSnapshotStoreCorrupted = class extends Error {
+	name = "JsonlSnapshotStoreCorrupted";
+};
+async function loadJsonlSnapshotStore(options) {
+	const raw = await readPersistenceFile(options.filePath);
+	if (raw === void 0) return [];
+	const lines = raw.split("\n");
+	const latest = /* @__PURE__ */ new Map();
+	let lineCount = 0;
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index] ?? "";
+		if (!line.trim()) continue;
+		lineCount += 1;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			if (index === lines.length - 1) {
+				await truncateAtLine(options.filePath, lines, index);
+				break;
+			}
+			throw new JsonlSnapshotStoreCorrupted(`${options.errorLabel} JSONL at line ${index + 1} is not valid JSON`);
+		}
+		if (!isRecord(parsed) || parsed.version !== options.version) throw new JsonlSnapshotStoreCorrupted(`unsupported ${options.errorLabel} version at line ${index + 1}`);
+		if (isRecord(parsed.snapshot)) {
+			if (!Array.isArray(parsed.snapshot.records)) throw new JsonlSnapshotStoreCorrupted(`invalid ${options.errorLabel} snapshot at line ${index + 1}`);
+			latest.clear();
+			for (const value of parsed.snapshot.records) {
+				if (!options.isRecord(value)) throw new JsonlSnapshotStoreCorrupted(`invalid ${options.errorLabel} snapshot at line ${index + 1}`);
+				latest.set(options.keyOf(value), structuredClone(value));
+			}
+			continue;
+		}
+		if (!options.isRecord(parsed.record)) throw new JsonlSnapshotStoreCorrupted(`invalid ${options.errorLabel} record at line ${index + 1}`);
+		const record = parsed.record;
+		const previous = latest.get(options.keyOf(record));
+		const invalid = options.validateSequence(previous, record, index + 1);
+		if (invalid) throw new JsonlSnapshotStoreCorrupted(`invalid ${options.errorLabel} ${invalid} at line ${index + 1}`);
+		latest.set(options.keyOf(record), structuredClone(record));
+	}
+	if (lineCount >= options.compactThreshold) await writeJsonlSnapshot(options.filePath, options.version, [...latest.values()]);
+	return [...latest.values()];
+}
+async function appendJsonlRecord(filePath, version, record) {
+	await mkdir(dirname(filePath), { recursive: true });
+	await appendFile(filePath, `${JSON.stringify({
+		record,
+		version
+	})}\n`, "utf8");
+}
+async function writeJsonlSnapshot(filePath, version, records) {
+	await mkdir(dirname(filePath), { recursive: true });
+	await writeFile(filePath, `${JSON.stringify({
+		snapshot: { records },
+		version
+	})}\n`, "utf8");
+}
+async function truncateAtLine(filePath, lines, lineIndex) {
+	let offset = 0;
+	for (let index = 0; index < lineIndex; index += 1) offset += (lines[index] ?? "").length + 1;
+	await truncate(filePath, offset);
+}
+//#endregion
+//#region src/persistence/files/write-atomic-text-file.ts
+/** Replace one UTF-8 text file through a same-directory temporary file. */
+async function writeAtomicTextFile(filePath, contents, options = {}) {
+	const directory = dirname(filePath);
+	await mkdir(directory, { recursive: true });
+	const existingMode = await readMode(filePath);
+	const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(temporaryPath, contents, {
+			encoding: "utf8",
+			flag: "wx",
+			mode: existingMode ?? options.mode
+		});
+		if (options.durable === true) await syncFile(temporaryPath);
+		await rename(temporaryPath, filePath);
+		if (options.durable === true) await syncDirectory(directory);
+	} catch (error) {
+		await unlink(temporaryPath).catch(() => void 0);
+		throw error;
+	}
+}
+async function readMode(filePath) {
+	try {
+		return (await stat(filePath)).mode & 4095;
+	} catch (error) {
+		if (isMissing(error)) return void 0;
+		throw error;
+	}
+}
+async function syncFile(filePath) {
+	const handle = await open(filePath, "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+async function syncDirectory(directory) {
+	const handle = await open(directory, "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+function isMissing(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+//#region src/persistence/files/write-persistence-file.ts
+async function writePersistenceFile(filePath, value) {
+	await writeAtomicTextFile(filePath, `${JSON.stringify(value)}\n`);
+}
+//#endregion
+export { JsonlSnapshotStoreCorrupted, appendJsonlRecord, isNodeErrorWithCode, isRecord, loadJsonlSnapshotStore, readPersistenceFile, writeAtomicTextFile, writeJsonlSnapshot, writePersistenceFile };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@rivus/platform",
+  "version": "0.16.2",
+  "description": "Shared technical primitives for Rivus packages.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": "^24.11.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerfectPan/rivus-agent.git",
+    "directory": "packages/platform"
+  },
+  "homepage": "https://github.com/PerfectPan/rivus-agent#readme",
+  "bugs": {
+    "url": "https://github.com/PerfectPan/rivus-agent/issues"
+  },
+  "exports": {
+    "./concurrency": {
+      "types": "./dist/concurrency/index.d.ts",
+      "import": "./dist/concurrency/index.js",
+      "default": "./dist/concurrency/index.js"
+    },
+    "./filesystem": {
+      "types": "./dist/filesystem/index.d.ts",
+      "import": "./dist/filesystem/index.js",
+      "default": "./dist/filesystem/index.js"
+    },
+    "./identity": {
+      "types": "./dist/identity/index.d.ts",
+      "import": "./dist/identity/index.js",
+      "default": "./dist/identity/index.js"
+    },
+    "./persistence": {
+      "types": "./dist/persistence/index.d.ts",
+      "import": "./dist/persistence/index.js",
+      "default": "./dist/persistence/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "vp pack",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vp test --run"
+  },
+  "dependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}