rea-agents 0.3.0 → 0.4.0

package/dist/application/EvidenceBundleFiles.js

@@ -0,0 +1,127 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { parseEvidenceBundle, serializeEvidenceBundle, } from "../domain/evidenceBundle.js";
+import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+/** Read and validate a bounded evidence bundle inside an approved root. */
+export const readEvidenceBundle = async (path, policy) => {
+    if (policy.roots.length === 0)
+        return err(new EvidenceFileError("read", "disabled"));
+    try {
+        const canonicalPath = await realpath(resolve(path));
+        if (!(await isApproved(canonicalPath, policy.roots)))
+            return err(new EvidenceFileError("read", "outside-root"));
+        const stats = await lstat(canonicalPath);
+        if (!stats.isFile())
+            return err(new EvidenceFileError("read", "not-file"));
+        if (stats.size > policy.maxBytes)
+            return err(new EvidenceFileError("read", "too-large"));
+        const encoded = await readFile(canonicalPath);
+        if (encoded.byteLength > policy.maxBytes)
+            return err(new EvidenceFileError("read", "too-large"));
+        let decoded;
+        try {
+            decoded = JSON.parse(encoded.toString("utf8"));
+        }
+        catch (cause) {
+            return err(new EvidenceFileError("read", "invalid-json", { cause }));
+        }
+        const limits = validateJsonLimits(decoded, policy);
+        if (!limits.ok)
+            return limits;
+        try {
+            return ok(parseEvidenceBundle(decoded));
+        }
+        catch (cause) {
+            return err(new EvidenceIntegrityError("Evidence bundle validation failed", {
+                cause,
+            }));
+        }
+    }
+    catch (cause) {
+        return err(new EvidenceFileError("read", "io", { cause }));
+    }
+};
+/** Atomically write deterministic evidence JSON inside an approved root. */
+export const writeEvidenceBundle = async (bundle, path, overwrite, policy) => {
+    if (policy.roots.length === 0)
+        return err(new EvidenceFileError("write", "disabled"));
+    let encoded;
+    try {
+        encoded = serializeEvidenceBundle(bundle);
+    }
+    catch (cause) {
+        return err(new EvidenceIntegrityError("Evidence bundle validation failed", {
+            cause,
+        }));
+    }
+    const bytes = Buffer.byteLength(encoded, "utf8");
+    if (bytes > policy.maxBytes)
+        return err(new EvidenceFileError("write", "too-large"));
+    try {
+        const canonicalParent = await realpath(dirname(resolve(path)));
+        const destination = resolve(canonicalParent, basename(resolve(path)));
+        if (!(await isApproved(destination, policy.roots)))
+            return err(new EvidenceFileError("write", "outside-root"));
+        const existing = await lstat(destination).catch((cause) => {
+            if (isFileNotFound(cause))
+                return undefined;
+            throw cause;
+        });
+        if (existing !== undefined) {
+            if (!overwrite)
+                return err(new EvidenceFileError("write", "exists"));
+            if (!existing.isFile() || existing.isSymbolicLink())
+                return err(new EvidenceFileError("write", "not-file"));
+        }
+        await writeFileAtomic(destination, encoded, {
+            encoding: "utf8",
+            mode: 0o600,
+            fsync: true,
+        });
+        return ok({ path: destination, bytes });
+    }
+    catch (cause) {
+        return err(new EvidenceFileError("write", "io", { cause }));
+    }
+};
+const isApproved = async (candidate, roots) => {
+    for (const configuredRoot of roots) {
+        const root = await realpath(resolve(configuredRoot));
+        const relation = relative(root, candidate);
+        if (relation === "" ||
+            (!relation.startsWith("..") && !isAbsolute(relation)))
+            return true;
+    }
+    return false;
+};
+const validateJsonLimits = (root, policy) => {
+    const pending = [
+        { value: root, depth: 0 },
+    ];
+    let nodes = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        nodes += 1;
+        if (nodes > policy.maxNodes || current.depth > policy.maxDepth)
+            return err(new EvidenceFileError("read", "too-large"));
+        if (typeof current.value === "string" &&
+            current.value.length > policy.maxStringLength)
+            return err(new EvidenceFileError("read", "too-large"));
+        if (typeof current.value !== "object" || current.value === null)
+            continue;
+        for (const [key, value] of Object.entries(current.value)) {
+            if (key.length > policy.maxStringLength)
+                return err(new EvidenceFileError("read", "too-large"));
+            pending.push({ value, depth: current.depth + 1 });
+        }
+    }
+    return ok(null);
+};
+const isFileNotFound = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT";

package/dist/application/EvidenceLedger.js

@@ -1,56 +1,263 @@
-import { createEvidenceBundle, evidenceBundleSchema, } from "../domain/evidenceBundle.js";
+import { createEvidenceBundle, parseEvidenceBundle, } from "../domain/evidenceBundle.js";
+import { EvidenceIntegrityError, EvidenceLimitError, UnknownRegistryError, } from "../domain/errors.js";
 import { parseEvidence } from "../domain/evidence.js";
+import { createResidualUnknown, updateResidualUnknown, } from "../domain/residualUnknown.js";
+import { err, ok } from "../domain/result.js";
 /** Bounded, session-owned set of immutable evidence records. */
 export class EvidenceLedger {
     limits;
     #records = new Map();
+    #unknownRevisions = new Map();
+    #unknownHeads = new Map();
+    #bytes = 0;
     constructor(limits) {
         this.limits = limits;
         if (!Number.isSafeInteger(limits.maxRecords) || limits.maxRecords < 1)
             throw new RangeError("maxRecords must be a positive safe integer");
+        if (!Number.isSafeInteger(limits.maxBytes) || limits.maxBytes < 1)
+            throw new RangeError("maxBytes must be a positive safe integer");
     }
     /** Record evidence idempotently; conflicting content is rejected. */
     record(input) {
-        const evidence = parseEvidence(input);
+        let evidence;
+        try {
+            evidence = parseEvidence(input);
+        }
+        catch (cause) {
+            return err(new EvidenceIntegrityError("Evidence record validation failed", {
+                cause,
+            }));
+        }
         const existing = this.#records.get(evidence.evidence_id);
         if (existing !== undefined) {
-            if (!recordsAgree(existing, evidence))
-                throw new Error(`Conflicting evidence record: ${evidence.evidence_id}`);
-            return "duplicate";
+            return recordsAgree(existing, evidence)
+                ? ok("duplicate")
+                : err(new EvidenceIntegrityError("Conflicting evidence record"));
         }
         if (this.#records.size >= this.limits.maxRecords)
-            throw new RangeError("Evidence ledger record limit exceeded");
+            return err(new EvidenceLimitError("records", this.limits.maxRecords));
+        const bytes = serializedBytes(evidence);
+        if (this.#bytes + bytes > this.limits.maxBytes)
+            return err(new EvidenceLimitError("bytes", this.limits.maxBytes));
         this.#records.set(evidence.evidence_id, evidence);
-        return "added";
+        this.#bytes += bytes;
+        return ok("added");
     }
     /** Validate an entire bundle before atomically merging its records. */
     import(input) {
-        const bundle = evidenceBundleSchema.parse(input);
+        let bundle;
+        try {
+            bundle = parseEvidenceBundle(input);
+        }
+        catch (cause) {
+            return err(new EvidenceIntegrityError("Evidence bundle validation failed", {
+                cause,
+            }));
+        }
         const pending = new Map(this.#records);
-        for (const unparsed of bundle.records) {
-            const evidence = parseEvidence(unparsed);
+        for (const evidence of bundle.records) {
             const existing = pending.get(evidence.evidence_id);
             if (existing !== undefined && !recordsAgree(existing, evidence))
-                throw new Error(`Conflicting evidence record: ${evidence.evidence_id}`);
+                return err(new EvidenceIntegrityError("Conflicting evidence record"));
             pending.set(evidence.evidence_id, evidence);
         }
-        if (pending.size > this.limits.maxRecords)
-            throw new RangeError("Evidence ledger record limit exceeded");
+        const pendingUnknowns = new Map(this.#unknownRevisions);
+        for (const unknown of bundle.unknowns) {
+            const key = unknownRevisionKey(unknown);
+            const existing = pendingUnknowns.get(key);
+            if (existing !== undefined &&
+                existing.revision_digest !== unknown.revision_digest)
+                return err(new EvidenceIntegrityError("Conflicting unknown revision"));
+            pendingUnknowns.set(key, unknown);
+        }
+        const checked = this.#validateCandidate(pending, pendingUnknowns);
+        if (!checked.ok) {
+            if (checked.error instanceof UnknownRegistryError)
+                return err(new EvidenceIntegrityError("Evidence bundle unknown registry failed", {
+                    cause: checked.error,
+                }));
+            return err(checked.error);
+        }
         const added = pending.size - this.#records.size;
-        this.#records.clear();
-        for (const [id, evidence] of pending)
-            this.#records.set(id, evidence);
-        return added;
+        this.#commit(pending, pendingUnknowns, checked.value);
+        return ok(added);
     }
     /** Export records in deterministic, semantically irrelevant ID order. */
     export() {
-        return createEvidenceBundle([...this.#records.values()]);
+        return createEvidenceBundle([...this.#records.values()], [...this.#unknownRevisions.values()]);
+    }
+    /** Check whether one immutable Evidence ID is present in this ledger. */
+    has(evidenceId) {
+        return this.#records.has(evidenceId);
+    }
+    /** Return a detached immutable Evidence value by semantic ID. */
+    get(evidenceId) {
+        const evidence = this.#records.get(evidenceId);
+        return evidence === undefined ? undefined : structuredClone(evidence);
+    }
+    /** Create one approved unknown and atomically append its mutation evidence. */
+    recordUnknown(input, mutationEvidence) {
+        let parsedMutation;
+        try {
+            parsedMutation = parseEvidence(mutationEvidence);
+        }
+        catch (cause) {
+            return err(new EvidenceIntegrityError("Unknown mutation evidence is invalid", {
+                cause,
+            }));
+        }
+        let unknown;
+        try {
+            unknown = createResidualUnknown(input, parsedMutation.evidence_id, parsedMutation.subject?.digest.sha256 ?? null);
+        }
+        catch (cause) {
+            return err(new UnknownRegistryError("invalid-transition", { cause }));
+        }
+        if (this.#unknownHeads.has(unknown.unknown_id))
+            return err(new UnknownRegistryError("already-exists"));
+        return this.#appendUnknown(unknown, parsedMutation);
+    }
+    /** Atomically record derived Evidence and an approved residual unknown. */
+    recordWithUnknown(evidenceInput, input, mutationInput) {
+        let evidence;
+        let mutation;
+        try {
+            evidence = parseEvidence(evidenceInput);
+            mutation = parseEvidence(mutationInput);
+        }
+        catch (cause) {
+            return err(new EvidenceIntegrityError("Atomic Evidence validation failed", {
+                cause,
+            }));
+        }
+        const existingEvidence = this.#records.get(evidence.evidence_id);
+        if (existingEvidence !== undefined &&
+            !recordsAgree(existingEvidence, evidence))
+            return err(new EvidenceIntegrityError("Conflicting evidence record"));
+        let unknown;
+        try {
+            unknown = createResidualUnknown(input, mutation.evidence_id, mutation.subject?.digest.sha256 ?? null);
+        }
+        catch (cause) {
+            return err(new UnknownRegistryError("invalid-transition", { cause }));
+        }
+        const pendingRecords = new Map(this.#records);
+        pendingRecords.set(evidence.evidence_id, evidence);
+        const existingUnknown = this.#unknownHeads.get(unknown.unknown_id);
+        if (existingUnknown !== undefined) {
+            if (existingUnknown.revision !== 1 ||
+                existingUnknown.revision_digest !== unknown.revision_digest)
+                return err(new UnknownRegistryError("already-exists"));
+            const checked = this.#validateCandidate(pendingRecords, this.#unknownRevisions);
+            if (!checked.ok)
+                return checked;
+            this.#commit(pendingRecords, this.#unknownRevisions, checked.value);
+            return ok(null);
+        }
+        pendingRecords.set(mutation.evidence_id, mutation);
+        const pendingUnknowns = new Map(this.#unknownRevisions);
+        pendingUnknowns.set(unknownRevisionKey(unknown), unknown);
+        const checked = this.#validateCandidate(pendingRecords, pendingUnknowns);
+        if (!checked.ok)
+            return checked;
+        this.#commit(pendingRecords, pendingUnknowns, checked.value);
+        return ok(unknown);
+    }
+    /** Apply one approved full-state update using optimistic revision matching. */
+    updateUnknown(input, mutationEvidence) {
+        const current = this.#unknownHeads.get(input.unknown_id);
+        if (current === undefined)
+            return err(new UnknownRegistryError("not-found"));
+        if (current.revision !== input.expected_revision)
+            return err(new UnknownRegistryError("revision-conflict"));
+        let unknown;
+        try {
+            unknown = updateResidualUnknown(current, input, mutationEvidence.evidence_id);
+        }
+        catch (cause) {
+            return err(new UnknownRegistryError("invalid-transition", { cause }));
+        }
+        return this.#appendUnknown(unknown, mutationEvidence);
+    }
+    /** Query current heads in stable ID order. */
+    listUnknowns(filters = {}) {
+        return [...this.#unknownHeads.values()]
+            .filter((unknown) => (filters.status === undefined || unknown.status === filters.status) &&
+            (filters.severity === undefined ||
+                unknown.severity === filters.severity) &&
+            (filters.domain === undefined || unknown.domain === filters.domain))
+            .sort((left, right) => left.unknown_id.localeCompare(right.unknown_id));
+    }
+    /** Return current resolution validity; imported invalid states are rejected. */
+    verifyUnknownResolution(unknownId) {
+        const unknown = this.#unknownHeads.get(unknownId);
+        if (unknown === undefined)
+            return err(new UnknownRegistryError("not-found"));
+        return ok({
+            valid: unknown.status === "resolved",
+            truthVerified: unknown.resolution?.disposition === "verified",
+            unknown,
+        });
     }
     /** Clear records when the owning session closes. */
     clear() {
         this.#records.clear();
+        this.#unknownRevisions.clear();
+        this.#unknownHeads.clear();
+        this.#bytes = 0;
+    }
+    #appendUnknown(unknown, mutationEvidenceInput) {
+        let mutationEvidence;
+        try {
+            mutationEvidence = parseEvidence(mutationEvidenceInput);
+        }
+        catch (cause) {
+            return err(new EvidenceIntegrityError("Unknown mutation evidence is invalid", {
+                cause,
+            }));
+        }
+        const pendingRecords = new Map(this.#records);
+        pendingRecords.set(mutationEvidence.evidence_id, mutationEvidence);
+        const pendingUnknowns = new Map(this.#unknownRevisions);
+        pendingUnknowns.set(unknownRevisionKey(unknown), unknown);
+        const checked = this.#validateCandidate(pendingRecords, pendingUnknowns);
+        if (!checked.ok)
+            return checked;
+        this.#commit(pendingRecords, pendingUnknowns, checked.value);
+        return ok(unknown);
+    }
+    #validateCandidate(records, unknowns) {
+        if (records.size + unknowns.size > this.limits.maxRecords)
+            return err(new EvidenceLimitError("records", this.limits.maxRecords));
+        const bytes = [...records.values()].reduce((total, evidence) => total + serializedBytes(evidence), 0) +
+            [...unknowns.values()].reduce((total, unknown) => total + serializedBytes(unknown), 0);
+        if (bytes > this.limits.maxBytes)
+            return err(new EvidenceLimitError("bytes", this.limits.maxBytes));
+        try {
+            parseEvidenceBundle(createEvidenceBundle([...records.values()], [...unknowns.values()]));
+        }
+        catch (cause) {
+            return err(new UnknownRegistryError("integrity", { cause }));
+        }
+        return ok(bytes);
+    }
+    #commit(records, unknowns, bytes) {
+        this.#records.clear();
+        for (const [id, evidence] of records)
+            this.#records.set(id, evidence);
+        this.#unknownRevisions.clear();
+        this.#unknownHeads.clear();
+        for (const [key, unknown] of unknowns) {
+            this.#unknownRevisions.set(key, unknown);
+            const head = this.#unknownHeads.get(unknown.unknown_id);
+            if (head === undefined || head.revision < unknown.revision)
+                this.#unknownHeads.set(unknown.unknown_id, unknown);
+        }
+        this.#bytes = bytes;
     }
 }
+const serializedBytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
+const unknownRevisionKey = (unknown) => `${unknown.unknown_id}:${String(unknown.revision)}`;
 const recordsAgree = (left, right) => JSON.stringify(withoutLocalPath(left)) ===
     JSON.stringify(withoutLocalPath(right));
 const withoutLocalPath = (evidence) => ({

package/dist/application/FilesystemSnapshot.js

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, open, readdir, readlink } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+const isWithin = (candidate, root) => candidate === root ||
+    candidate.startsWith(`${root.endsWith("/") ? root.slice(0, -1) : root}/`);
+const hasSameIdentity = (before, after, expected) => before.dev === after.dev &&
+    before.ino === after.ino &&
+    (expected === "directory" ? after.isDirectory() : after.isSymbolicLink());
+const lstatIfPresent = async (path) => {
+    try {
+        return await lstat(path);
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return undefined;
+        throw cause;
+    }
+};
+const hashFile = async (path, maxBytes, signal) => {
+    const handle = await open(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+    try {
+        const stats = await handle.stat();
+        if (!stats.isFile() || stats.size > maxBytes)
+            return null;
+        const hash = createHash("sha256");
+        const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes));
+        let position = 0;
+        while (position < stats.size) {
+            signal?.throwIfAborted();
+            const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, stats.size - position), position);
+            if (bytesRead === 0)
+                return null;
+            hash.update(buffer.subarray(0, bytesRead));
+            position += bytesRead;
+        }
+        const after = await handle.stat();
+        if (after.size !== stats.size || after.mtimeMs !== stats.mtimeMs)
+            return null;
+        return hash.digest("hex");
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Capture bounded, root-aliased filesystem state without following symlinks. */
+export const snapshotRoots = async (scenario, signal) => {
+    const entries = [];
+    let remainingBytes = scenario.limits.file_bytes;
+    let truncated = false;
+    const visit = async (root, rootAlias, path, depth) => {
+        signal?.throwIfAborted();
+        if (entries.length >= scenario.limits.files ||
+            depth > scenario.limits.filesystem_depth) {
+            truncated = true;
+            return;
+        }
+        const stats = await lstatIfPresent(path);
+        if (stats === undefined)
+            return;
+        const relativePath = relative(root, path) || ".";
+        if (stats.isSymbolicLink()) {
+            const target = resolve(dirname(path), await readlink(path));
+            const afterRead = await lstat(path);
+            if (!hasSameIdentity(stats, afterRead, "symlink")) {
+                truncated = true;
+                return;
+            }
+            const safeTarget = isWithin(target, root)
+                ? relative(root, target) || "."
+                : "<outside-declared-root>";
+            if (safeTarget === "<outside-declared-root>")
+                truncated = true;
+            entries.push({
+                path: `${rootAlias}:${relativePath}`,
+                type: "symlink",
+                mode: stats.mode,
+                size: stats.size,
+                sha256: null,
+                symlink_target: safeTarget,
+            });
+            return;
+        }
+        if (stats.isFile()) {
+            const sha256 = remainingBytes >= stats.size
+                ? await hashFile(path, remainingBytes, signal)
+                : null;
+            remainingBytes -= sha256 === null ? 0 : stats.size;
+            if (sha256 === null)
+                truncated = true;
+            entries.push({
+                path: `${rootAlias}:${relativePath}`,
+                type: "file",
+                mode: stats.mode,
+                size: stats.size,
+                sha256,
+                symlink_target: null,
+            });
+            return;
+        }
+        const type = stats.isDirectory() ? "directory" : "other";
+        entries.push({
+            path: `${rootAlias}:${relativePath}`,
+            type,
+            mode: stats.mode,
+            size: stats.size,
+            sha256: null,
+            symlink_target: null,
+        });
+        if (type !== "directory")
+            return;
+        const children = await readdir(path);
+        const afterRead = await lstat(path);
+        if (!hasSameIdentity(stats, afterRead, "directory")) {
+            truncated = true;
+            return;
+        }
+        for (const child of children.sort())
+            await visit(root, rootAlias, join(path, child), depth + 1);
+    };
+    for (const [index, root] of scenario.filesystem_roots.entries())
+        await visit(root, `root_${String(index)}`, root, 0);
+    return { files: entries, truncated };
+};