@litfamily/litcodex 1.0.0

package/node_modules/@litcodex/lit-loop/dist/skill-observer.js

@@ -0,0 +1,946 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { performance } from "node:perf_hooks";
+import { TextDecoder } from "node:util";
+import { redactSecrets } from "./redaction.js";
+export const OBSERVER_SIGNALS = Object.freeze(["correction", "repetition", "coverage-gap"]);
+export const OBSERVER_RECORD_STATE_UNKNOWN = "OBSERVER_RECORD_STATE_UNKNOWN";
+export const OBSERVER_RECORD_COMMITTED_CLEANUP_FAILED = "OBSERVER_RECORD_COMMITTED_CLEANUP_FAILED";
+const INPUT_FIELDS = Object.freeze(["signal", "skillId", "observed", "proposal"]);
+const PERSISTED_FIELDS = Object.freeze([...INPUT_FIELDS, "applied"]);
+const TEXT_CEILING = 1000;
+const SKILL_ID = /^[a-z][a-z0-9-]{0,63}$/u;
+const MAX_LOG_BYTES = 1024 * 1024;
+const LOCK_WAIT_MS = 250;
+const LOCK_POLL_MS = 10;
+const LOCK_WAIT_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+const OBSERVER_DIR = "skill-observer";
+const LOG_NAME = "observations.jsonl";
+const LOCK_SUFFIX = ".lock";
+const LOCK_OWNER_NAME = "owner";
+const LOCK_OWNER_MAX_BYTES = 512;
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+const CREDENTIAL_URI_PATTERN = /[a-z][a-z0-9+.-]*:\/\/[^/?#\s]*@/iu;
+const WINDOWS_DRIVE_ABSOLUTE = /^[A-Za-z]:[\\/]/u;
+const WINDOWS_UNC_ABSOLUTE = /^\\\\/u;
+const LOCK_OWNER_TOKEN = /^[A-Za-z0-9:_-]{1,128}$/u;
+export class SkillObserverError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "SkillObserverError";
+        this.code = code;
+    }
+}
+function safeRootPath(root) {
+    if (typeof root !== "string") {
+        throw new SkillObserverError("OBSERVER_PATH_UNSAFE", "the project root must be a path string");
+    }
+    if (process.platform !== "win32" && (WINDOWS_DRIVE_ABSOLUTE.test(root) || WINDOWS_UNC_ABSOLUTE.test(root))) {
+        throw new SkillObserverError("OBSERVER_PATH_UNSAFE", "the project root uses a foreign absolute path format");
+    }
+    try {
+        return resolve(root);
+    }
+    catch {
+        throw new SkillObserverError("OBSERVER_PATH_UNSAFE", "the project root could not be resolved safely");
+    }
+}
+export function observationLogPath(root = process.cwd()) {
+    return join(safeRootPath(root), ".litcodex", OBSERVER_DIR, LOG_NAME);
+}
+function errnoCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? error.code
+        : undefined;
+}
+function pathIsWithin(root, candidate) {
+    const child = relative(root, candidate);
+    return child === "" || (!isAbsolute(child) && child !== ".." && !child.startsWith(`..${sep}`));
+}
+function pathsFor(root) {
+    const absoluteRoot = safeRootPath(root);
+    const stateDir = join(absoluteRoot, ".litcodex");
+    const observerDir = join(stateDir, OBSERVER_DIR);
+    const log = join(observerDir, LOG_NAME);
+    const lock = join(absoluteRoot, `${OBSERVER_DIR}${LOCK_SUFFIX}`);
+    if (![stateDir, observerDir, log, lock].every((path) => pathIsWithin(absoluteRoot, path))) {
+        throw new SkillObserverError("OBSERVER_PATH_UNSAFE", "the observation path escapes the project root");
+    }
+    return { root: absoluteRoot, stateDir, observerDir, log, lock };
+}
+function pathUnsafe(path, detail) {
+    return new SkillObserverError("OBSERVER_PATH_UNSAFE", `${detail}: ${path}`);
+}
+function isDarwinSystemAlias(path, target) {
+    return (process.platform === "darwin" &&
+        ((path === "/var" && target === "/private/var") || (path === "/tmp" && target === "/private/tmp")));
+}
+function assertSafeRootParents(root) {
+    let current = root;
+    for (;;) {
+        let entry;
+        try {
+            entry = lstatSync(current);
+        }
+        catch (error) {
+            if (errnoCode(error) !== "ENOENT") {
+                throw pathUnsafe(current, `cannot inspect a requested-root parent (${errnoCode(error) ?? "unknown error"})`);
+            }
+        }
+        if (entry?.isSymbolicLink()) {
+            if (current === root)
+                throw pathUnsafe(current, "the requested root is a symbolic link");
+            let target;
+            try {
+                target = realpathSync(current);
+            }
+            catch (error) {
+                throw pathUnsafe(current, `cannot resolve a requested-root parent (${errnoCode(error) ?? "unknown error"})`);
+            }
+            if (!isDarwinSystemAlias(current, target)) {
+                throw pathUnsafe(current, "a requested-root parent is a symbolic link");
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return;
+        current = parent;
+    }
+}
+function rootRealPath(paths, create) {
+    let rootStat;
+    assertSafeRootParents(paths.root);
+    try {
+        rootStat = lstatSync(paths.root);
+    }
+    catch (error) {
+        if (errnoCode(error) !== "ENOENT") {
+            throw pathUnsafe(paths.root, `cannot inspect the project root (${errnoCode(error) ?? "unknown error"})`);
+        }
+        if (!create)
+            return undefined;
+        try {
+            mkdirSync(paths.root, { mode: 0o700, recursive: true });
+            rootStat = lstatSync(paths.root);
+        }
+        catch (createError) {
+            throw pathUnsafe(paths.root, `cannot create the project root (${errnoCode(createError) ?? "unknown error"})`);
+        }
+    }
+    if (rootStat === undefined)
+        throw pathUnsafe(paths.root, "the project root is unavailable");
+    if (rootStat.isSymbolicLink())
+        throw pathUnsafe(paths.root, "the project root is a symbolic link");
+    if (!rootStat.isDirectory())
+        throw pathUnsafe(paths.root, "the project root is not a directory");
+    try {
+        return realpathSync(paths.root);
+    }
+    catch (error) {
+        throw pathUnsafe(paths.root, `cannot resolve the project root (${errnoCode(error) ?? "unknown error"})`);
+    }
+}
+function checkDirectory(path, rootReal, create) {
+    let directory;
+    try {
+        directory = lstatSync(path);
+    }
+    catch (error) {
+        if (errnoCode(error) !== "ENOENT") {
+            throw pathUnsafe(path, `cannot inspect an observer directory (${errnoCode(error) ?? "unknown error"})`);
+        }
+        if (!create)
+            return undefined;
+        try {
+            mkdirSync(path, { mode: 0o700 });
+            directory = lstatSync(path);
+        }
+        catch (createError) {
+            if (errnoCode(createError) !== "EEXIST") {
+                throw pathUnsafe(path, `cannot create the observer directory (${errnoCode(createError) ?? "unknown error"})`);
+            }
+            try {
+                directory = lstatSync(path);
+            }
+            catch (raceError) {
+                throw pathUnsafe(path, `cannot inspect the observer directory (${errnoCode(raceError) ?? "unknown error"})`);
+            }
+        }
+    }
+    if (directory === undefined)
+        throw pathUnsafe(path, "the observer directory is unavailable");
+    if (directory.isSymbolicLink())
+        throw pathUnsafe(path, "an observer parent is a symbolic link");
+    if (!directory.isDirectory())
+        throw pathUnsafe(path, "an observer parent is not a directory");
+    let real;
+    try {
+        real = realpathSync(path);
+    }
+    catch (error) {
+        throw pathUnsafe(path, `cannot resolve an observer parent (${errnoCode(error) ?? "unknown error"})`);
+    }
+    if (!pathIsWithin(rootReal, real))
+        throw pathUnsafe(path, "an observer parent escapes the project root");
+    return { dev: directory.dev, ino: directory.ino, birthtimeMs: directory.birthtimeMs };
+}
+function writablePaths(root) {
+    const paths = pathsFor(root);
+    const realRoot = rootRealPath(paths, true);
+    if (realRoot === undefined)
+        throw pathUnsafe(paths.root, "the project root is unavailable");
+    const stateIdentity = checkDirectory(paths.stateDir, realRoot, true);
+    const observerIdentity = checkDirectory(paths.observerDir, realRoot, true);
+    if (stateIdentity === undefined || observerIdentity === undefined) {
+        throw pathUnsafe(paths.observerDir, "the observer directory is unavailable");
+    }
+    return { ...paths, rootReal: realRoot, stateIdentity, observerIdentity };
+}
+function readablePaths(root) {
+    const paths = pathsFor(root);
+    const realRoot = rootRealPath(paths, false);
+    if (realRoot === undefined)
+        return undefined;
+    const stateIdentity = checkDirectory(paths.stateDir, realRoot, false);
+    const observerIdentity = checkDirectory(paths.observerDir, realRoot, false);
+    if (stateIdentity === undefined || observerIdentity === undefined)
+        return undefined;
+    return { ...paths, rootReal: realRoot, stateIdentity, observerIdentity };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function flatten(value) {
+    return value
+        .replace(/[\p{Cf}\u0080-\u009f]/gu, "")
+        .replace(/\p{Cc}/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim()
+        .slice(0, TEXT_CEILING);
+}
+function containsSecret(value) {
+    return redactSecrets(value) !== value || CREDENTIAL_URI_PATTERN.test(value);
+}
+function validateObservation(value, persisted) {
+    if (!isRecord(value)) {
+        throw new SkillObserverError("OBSERVER_SHAPE_INVALID", "an observation must be an object");
+    }
+    const fields = persisted ? PERSISTED_FIELDS : INPUT_FIELDS;
+    // The unknown key names are never echoed or persisted: a stray field name can carry secrets.
+    if (Object.keys(value).some((key) => !fields.includes(key))) {
+        throw new SkillObserverError("OBSERVER_FIELD_UNKNOWN", "an observation carries a field outside the contract");
+    }
+    if (persisted) {
+        const missing = PERSISTED_FIELDS.filter((field) => !Object.hasOwn(value, field));
+        if (missing.length > 0) {
+            throw new SkillObserverError("OBSERVER_FIELD_MISSING", `missing observation field: ${missing.join(", ")}`);
+        }
+    }
+    if (!OBSERVER_SIGNALS.includes(value["signal"])) {
+        throw new SkillObserverError("OBSERVER_SIGNAL_UNKNOWN", `signal must be one of ${OBSERVER_SIGNALS.join(", ")}`);
+    }
+    if (typeof value["skillId"] !== "string" || !SKILL_ID.test(value["skillId"])) {
+        throw new SkillObserverError("OBSERVER_SKILL_ID_INVALID", "skillId must be a lowercase skill identifier");
+    }
+    for (const field of ["observed", "proposal"]) {
+        const text = value[field];
+        if (typeof text !== "string" || text.trim() === "") {
+            throw new SkillObserverError("OBSERVER_TEXT_MISSING", `${field} must be non-empty text`);
+        }
+        const spaced = text
+            .replace(/[\p{Cc}\p{Cf}]/gu, " ")
+            .replace(/\s+/gu, " ")
+            .trim();
+        if (containsSecret(text) || containsSecret(flatten(text)) || containsSecret(spaced)) {
+            throw new SkillObserverError("OBSERVER_SECRET_REFUSED", `${field} looks like it carries a credential and was refused before any write`);
+        }
+        if (flatten(text).length === 0) {
+            throw new SkillObserverError("OBSERVER_TEXT_MISSING", `${field} must contain usable text`);
+        }
+        if (persisted && (text.length > TEXT_CEILING || flatten(text) !== text)) {
+            throw new SkillObserverError("OBSERVER_TEXT_NOT_CANONICAL", `${field} is not canonical bounded text`);
+        }
+    }
+    if (persisted && value["applied"] !== false) {
+        throw new SkillObserverError("OBSERVER_APPLIED_INVALID", "applied must be the boolean false");
+    }
+}
+function logEntryState(path) {
+    let entry;
+    try {
+        entry = lstatSync(path);
+    }
+    catch (error) {
+        if (errnoCode(error) === "ENOENT")
+            return "missing";
+        throw new SkillObserverError("OBSERVER_LOG_UNAVAILABLE", `cannot inspect the observation log: ${path}`);
+    }
+    if (entry === undefined) {
+        throw new SkillObserverError("OBSERVER_LOG_UNAVAILABLE", `cannot inspect the observation log: ${path}`);
+    }
+    if (entry.isSymbolicLink()) {
+        throw new SkillObserverError("OBSERVER_LOG_SYMLINK", "the observation log is a symbolic link");
+    }
+    if (!entry.isFile()) {
+        throw new SkillObserverError("OBSERVER_LOG_NOT_REGULAR", "the observation log is not a regular file");
+    }
+    if (entry.nlink !== 1)
+        throw new SkillObserverError("OBSERVER_LOG_HARD_LINK", "the observation log has hard links");
+    if ((entry.mode & 0o077) !== 0) {
+        throw new SkillObserverError("OBSERVER_LOG_PERMISSIONS", "the observation log has group or world permission bits");
+    }
+    return "present";
+}
+function assertRegularLogHandle(handle) {
+    const entry = fstatSync(handle);
+    if (!entry.isFile()) {
+        throw new SkillObserverError("OBSERVER_LOG_NOT_REGULAR", "the observation log is not a regular file");
+    }
+    if (entry.nlink !== 1)
+        throw new SkillObserverError("OBSERVER_LOG_HARD_LINK", "the observation log has hard links");
+    if ((entry.mode & 0o077) !== 0) {
+        throw new SkillObserverError("OBSERVER_LOG_PERMISSIONS", "the observation log has group or world permission bits");
+    }
+}
+function removeCreatedLogAfterOpenFailure(paths, handle) {
+    let descriptor;
+    try {
+        descriptor = fstatSync(handle);
+    }
+    catch {
+        throw new SkillObserverError("OBSERVER_LOG_OPEN_FAILED", "the newly created observation log could not be inspected");
+    }
+    let namedPath;
+    try {
+        namedPath = lstatSync(paths.log);
+    }
+    catch (error) {
+        if (errnoCode(error) === "ENOENT")
+            return;
+        throw new SkillObserverError("OBSERVER_LOG_OPEN_FAILED", "the newly created observation log could not be inspected");
+    }
+    if (namedPath.isSymbolicLink() ||
+        !namedPath.isFile() ||
+        namedPath.nlink !== 1 ||
+        namedPath.dev !== descriptor.dev ||
+        namedPath.ino !== descriptor.ino ||
+        namedPath.ctimeMs !== descriptor.ctimeMs ||
+        namedPath.birthtimeMs !== descriptor.birthtimeMs) {
+        throw new SkillObserverError("OBSERVER_LOG_PATH_CHANGED", "the newly created observation log path no longer identifies the opened file");
+    }
+    try {
+        unlinkSync(paths.log);
+    }
+    catch {
+        throw new SkillObserverError("OBSERVER_LOG_OPEN_FAILED", "the newly created observation log could not be removed");
+    }
+    try {
+        lstatSync(paths.log);
+    }
+    catch (error) {
+        if (errnoCode(error) === "ENOENT")
+            return;
+    }
+    throw new SkillObserverError("OBSERVER_LOG_OPEN_FAILED", "the newly created observation log could not be removed");
+}
+function assertLogPathIdentity(path, descriptor) {
+    let namedPath;
+    try {
+        namedPath = lstatSync(path);
+    }
+    catch {
+        throw new SkillObserverError("OBSERVER_LOG_PATH_CHANGED", "the observation log path no longer identifies the opened file");
+    }
+    if (namedPath.dev !== descriptor.dev ||
+        namedPath.ino !== descriptor.ino ||
+        namedPath.ctimeMs !== descriptor.ctimeMs ||
+        namedPath.birthtimeMs !== descriptor.birthtimeMs) {
+        throw new SkillObserverError("OBSERVER_LOG_PATH_CHANGED", "the observation log path no longer identifies the opened file");
+    }
+}
+function openLogForAppend(paths) {
+    assertTrustedParents(paths);
+    const state = logEntryState(paths.log);
+    assertTrustedParents(paths);
+    try {
+        const handle = openSync(paths.log, constants.O_RDWR |
+            constants.O_APPEND |
+            NO_FOLLOW |
+            (state === "missing" ? constants.O_CREAT | constants.O_EXCL : 0), 0o600);
+        try {
+            assertRegularLogHandle(handle);
+            try {
+                assertTrustedParents(paths);
+            }
+            catch (error) {
+                if (state === "missing")
+                    removeCreatedLogAfterOpenFailure(paths, handle);
+                throw error;
+            }
+            return handle;
+        }
+        catch (error) {
+            closeSync(handle);
+            throw error;
+        }
+    }
+    catch (error) {
+        if (error instanceof SkillObserverError)
+            throw error;
+        if (errnoCode(error) === "EEXIST" && state === "missing") {
+            try {
+                const handle = openSync(paths.log, constants.O_RDWR | constants.O_APPEND | NO_FOLLOW);
+                try {
+                    assertRegularLogHandle(handle);
+                    return handle;
+                }
+                catch (innerError) {
+                    closeSync(handle);
+                    throw innerError;
+                }
+            }
+            catch (retryError) {
+                if (retryError instanceof SkillObserverError)
+                    throw retryError;
+                throw new SkillObserverError("OBSERVER_LOG_OPEN_FAILED", `cannot open the observation log: ${paths.log}`);
+            }
+        }
+        if (errnoCode(error) === "ELOOP" && state === "missing") {
+            throw new SkillObserverError("OBSERVER_LOG_SYMLINK", "the observation log became a symbolic link");
+        }
+        throw new SkillObserverError("OBSERVER_LOG_OPEN_FAILED", `cannot open the observation log: ${paths.log}`);
+    }
+}
+function openLogForRead(path) {
+    if (logEntryState(path) === "missing")
+        return undefined;
+    try {
+        const handle = openSync(path, constants.O_RDONLY | NO_FOLLOW);
+        try {
+            assertRegularLogHandle(handle);
+            return handle;
+        }
+        catch (error) {
+            closeSync(handle);
+            throw error;
+        }
+    }
+    catch (error) {
+        if (error instanceof SkillObserverError)
+            throw error;
+        if (errnoCode(error) === "ELOOP") {
+            throw new SkillObserverError("OBSERVER_LOG_SYMLINK", "the observation log became a symbolic link");
+        }
+        if (errnoCode(error) === "ENOENT")
+            return undefined;
+        throw new SkillObserverError("OBSERVER_LOG_OPEN_FAILED", `cannot open the observation log: ${path}`);
+    }
+}
+function readLogBytes(path, handle) {
+    const before = fstatSync(handle);
+    if (before.size > MAX_LOG_BYTES) {
+        throw new SkillObserverError("OBSERVER_LOG_SIZE_EXCEEDED", "the observation log exceeds the 1 MiB limit");
+    }
+    let bytes;
+    try {
+        bytes = readFileSync(handle);
+    }
+    catch {
+        throw new SkillObserverError("OBSERVER_LOG_READ_FAILED", "the observation log could not be read");
+    }
+    if (bytes.byteLength !== before.size) {
+        throw new SkillObserverError("OBSERVER_LOG_CONCURRENT_MODIFICATION", "the observation log changed during the read");
+    }
+    let after;
+    try {
+        after = fstatSync(handle);
+    }
+    catch {
+        throw new SkillObserverError("OBSERVER_LOG_CONCURRENT_MODIFICATION", "the observation log changed during the read");
+    }
+    const changedTimestamp = (field) => {
+        const beforeValue = before[field];
+        const afterValue = after[field];
+        return typeof beforeValue === "number" && typeof afterValue === "number" && beforeValue !== afterValue;
+    };
+    if (before.dev !== after.dev ||
+        before.ino !== after.ino ||
+        before.size !== after.size ||
+        changedTimestamp("ctimeMs") ||
+        changedTimestamp("mtimeMs")) {
+        throw new SkillObserverError("OBSERVER_LOG_CONCURRENT_MODIFICATION", "the observation log changed during the read");
+    }
+    assertLogPathIdentity(path, after);
+    return bytes;
+}
+function parseLog(bytes) {
+    if (bytes.byteLength > MAX_LOG_BYTES) {
+        throw new SkillObserverError("OBSERVER_LOG_SIZE_EXCEEDED", "the observation log exceeds the 1 MiB limit");
+    }
+    if (bytes.byteLength === 0)
+        return [];
+    let raw;
+    try {
+        raw = UTF8_DECODER.decode(bytes);
+    }
+    catch {
+        throw new SkillObserverError("OBSERVER_LOG_MALFORMED", "the observation log is not valid UTF-8");
+    }
+    const content = raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+    const records = [];
+    for (const [index, line] of content.split("\n").entries()) {
+        if (line.trim() === "") {
+            throw new SkillObserverError("OBSERVER_LOG_MALFORMED", `observation log record ${index + 1} is empty`);
+        }
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            throw new SkillObserverError("OBSERVER_LOG_MALFORMED", `observation log record ${index + 1} is not JSON`);
+        }
+        try {
+            validateObservation(value, true);
+        }
+        catch (error) {
+            if (error instanceof SkillObserverError && error.code === "OBSERVER_SECRET_REFUSED")
+                throw error;
+            throw new SkillObserverError("OBSERVER_LOG_MALFORMED", `observation log record ${index + 1} is invalid`);
+        }
+        if (JSON.stringify(value) !== line) {
+            throw new SkillObserverError("OBSERVER_LOG_MALFORMED", `observation log record ${index + 1} is not canonical JSON`);
+        }
+        records.push(value);
+    }
+    return records;
+}
+function sleepForLock(milliseconds) {
+    Atomics.wait(LOCK_WAIT_BUFFER, 0, 0, milliseconds);
+}
+function monotonicNowMs() {
+    return performance.now();
+}
+function assertTrustedParents(paths) {
+    for (const [path, expected] of [
+        [paths.stateDir, paths.stateIdentity],
+        [paths.observerDir, paths.observerIdentity],
+    ]) {
+        let current;
+        try {
+            current = lstatSync(path);
+        }
+        catch {
+            throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "an observer parent changed during lock creation");
+        }
+        if (current.isSymbolicLink() ||
+            !current.isDirectory() ||
+            current.dev !== expected.dev ||
+            current.ino !== expected.ino ||
+            current.birthtimeMs !== expected.birthtimeMs) {
+            throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "an observer parent changed during lock creation");
+        }
+    }
+}
+function lockDirectoryIdentity(path, rootReal) {
+    let lock;
+    try {
+        lock = lstatSync(path);
+    }
+    catch (error) {
+        if (errnoCode(error) === "ENOENT")
+            return undefined;
+        throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "the observation log lock could not be inspected");
+    }
+    if (lock.isSymbolicLink() || !lock.isDirectory()) {
+        throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "the observation log lock is not a private directory");
+    }
+    let real;
+    try {
+        real = realpathSync(path);
+    }
+    catch (error) {
+        // A contender may release the lock between lstatSync and realpathSync. Treat that
+        // disappearance as a retryable observation, not as an unsafe path.
+        if (errnoCode(error) === "ENOENT")
+            return undefined;
+        throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "the observation log lock could not be resolved");
+    }
+    if (!pathIsWithin(rootReal, real)) {
+        throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "the observation log lock escapes the project root");
+    }
+    return { dev: lock.dev, ino: lock.ino, birthtimeMs: lock.birthtimeMs };
+}
+function assertLockDirectory(path, rootReal) {
+    return lockDirectoryIdentity(path, rootReal) !== undefined;
+}
+function parseLockOwner(value) {
+    if (value.length === 0 || Buffer.byteLength(value, "utf8") > LOCK_OWNER_MAX_BYTES || value !== value.trim()) {
+        return undefined;
+    }
+    const legacy = /^([1-9][0-9]*):([A-Za-z0-9_-]{1,96})$/u.exec(value);
+    if (legacy !== null) {
+        const pid = Number(legacy[1]);
+        const token = legacy[2];
+        if (typeof token === "string" && Number.isSafeInteger(pid) && pid > 0 && LOCK_OWNER_TOKEN.test(token))
+            return { pid, token };
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(parsed))
+        return undefined;
+    const pid = parsed["pid"];
+    const token = parsed["token"];
+    if (!Number.isSafeInteger(pid) ||
+        pid <= 0 ||
+        typeof token !== "string" ||
+        !LOCK_OWNER_TOKEN.test(token)) {
+        return undefined;
+    }
+    return { pid: pid, token };
+}
+function ownerProcessState(pid) {
+    try {
+        process.kill(pid, 0);
+        return "live";
+    }
+    catch (error) {
+        const code = errnoCode(error);
+        if (code === "ESRCH")
+            return "dead";
+        if (code === "EPERM")
+            return "live";
+        return "unknown";
+    }
+}
+function inspectLock(paths) {
+    const identity = lockDirectoryIdentity(paths.lock, paths.rootReal);
+    if (identity === undefined)
+        return undefined;
+    const ownerPath = join(paths.lock, LOCK_OWNER_NAME);
+    let ownerStat;
+    try {
+        ownerStat = lstatSync(ownerPath);
+    }
+    catch (error) {
+        if (errnoCode(error) === "ENOENT")
+            return { identity, owner: undefined, state: "unknown" };
+        return { identity, owner: undefined, state: "unknown" };
+    }
+    if (ownerStat.isSymbolicLink() ||
+        !ownerStat.isFile() ||
+        ownerStat.nlink !== 1 ||
+        (ownerStat.mode & 0o077) !== 0 ||
+        ownerStat.size > LOCK_OWNER_MAX_BYTES) {
+        throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "the observation log lock owner is unsafe");
+    }
+    let raw;
+    try {
+        raw = readFileSync(ownerPath, "utf8");
+    }
+    catch {
+        return { identity, owner: undefined, state: "unknown" };
+    }
+    const owner = parseLockOwner(raw);
+    return owner === undefined
+        ? { identity, owner: undefined, state: "unknown" }
+        : {
+            identity,
+            owner,
+            state: ownerProcessState(owner.pid),
+        };
+}
+function sameLockOwner(left, right) {
+    return left?.pid === right?.pid && left?.token === right?.token;
+}
+function recoverStaleLock(paths, observed) {
+    if (observed.state !== "dead" || observed.owner === undefined)
+        return false;
+    const current = inspectLock(paths);
+    if (current === undefined ||
+        current.state !== "dead" ||
+        current.identity.dev !== observed.identity.dev ||
+        current.identity.ino !== observed.identity.ino ||
+        current.identity.birthtimeMs !== observed.identity.birthtimeMs ||
+        !sameLockOwner(current.owner, observed.owner)) {
+        return false;
+    }
+    const displaced = `${paths.lock}.stale.${randomUUID()}`;
+    try {
+        assertTrustedParents(paths);
+        const latest = inspectLock(paths);
+        if (latest === undefined ||
+            latest.state !== "dead" ||
+            latest.identity.dev !== observed.identity.dev ||
+            latest.identity.ino !== observed.identity.ino ||
+            latest.identity.birthtimeMs !== observed.identity.birthtimeMs ||
+            !sameLockOwner(latest.owner, observed.owner)) {
+            return false;
+        }
+        renameSync(paths.lock, displaced);
+    }
+    catch (error) {
+        const code = errnoCode(error);
+        if (code === "ENOENT" || code === "EEXIST" || code === "ENOTEMPTY")
+            return false;
+        if (error instanceof SkillObserverError)
+            throw error;
+        throw new SkillObserverError("OBSERVER_LOCK_RECOVERY_FAILED", "the stale observation lock could not be displaced");
+    }
+    try {
+        rmSync(displaced, { recursive: true, force: false });
+    }
+    catch {
+        throw new SkillObserverError("OBSERVER_LOCK_RECOVERY_FAILED", "the stale observation lock could not be cleaned up");
+    }
+    return true;
+}
+function acquireLock(paths) {
+    const lock = {
+        path: paths.lock,
+        ownerPath: join(paths.lock, LOCK_OWNER_NAME),
+        token: `${process.pid}:${randomUUID()}`,
+        paths,
+    };
+    const deadline = monotonicNowMs() + LOCK_WAIT_MS;
+    let created;
+    // Unknown owners are never reclaimed. A timeout leaves the lock for manual review.
+    for (;;) {
+        if (deadline - monotonicNowMs() <= 0) {
+            throw new SkillObserverError("OBSERVER_LOCK_TIMEOUT", "the observation log lock wait expired");
+        }
+        try {
+            assertTrustedParents(paths);
+            mkdirSync(lock.path, { mode: 0o700 });
+            const createdStat = lstatSync(lock.path);
+            if (createdStat.isSymbolicLink() || !createdStat.isDirectory()) {
+                throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "the observation log lock is not a private directory");
+            }
+            created = {
+                dev: createdStat.dev,
+                ino: createdStat.ino,
+                birthtimeMs: createdStat.birthtimeMs,
+            };
+            assertTrustedParents(paths);
+            if (!assertLockDirectory(lock.path, paths.rootReal)) {
+                throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "the observation log lock disappeared during creation");
+            }
+            try {
+                assertTrustedParents(paths);
+                writeFileSync(lock.ownerPath, lock.token, { encoding: "utf8", mode: 0o600, flag: "wx" });
+                assertTrustedParents(paths);
+                return lock;
+            }
+            catch (error) {
+                if (error instanceof SkillObserverError)
+                    throw error;
+                throw new SkillObserverError("OBSERVER_LOCK_FAILED", "the observation log lock owner could not be recorded");
+            }
+        }
+        catch (error) {
+            if (created !== undefined) {
+                try {
+                    const current = lstatSync(lock.path);
+                    if (current.isDirectory() &&
+                        !current.isSymbolicLink() &&
+                        current.dev === created.dev &&
+                        current.ino === created.ino &&
+                        current.birthtimeMs === created.birthtimeMs) {
+                        rmSync(lock.path, { recursive: true, force: false });
+                    }
+                }
+                catch {
+                    // Lock cleanup cannot change the fail-closed result.
+                }
+                created = undefined;
+            }
+            if (error instanceof SkillObserverError)
+                throw error;
+            if (errnoCode(error) !== "EEXIST") {
+                assertTrustedParents(paths);
+                throw new SkillObserverError("OBSERVER_LOCK_FAILED", "the observation log lock could not be created");
+            }
+            const inspection = inspectLock(paths);
+            if (inspection === undefined) {
+                const remaining = deadline - monotonicNowMs();
+                if (remaining <= 0) {
+                    throw new SkillObserverError("OBSERVER_LOCK_TIMEOUT", "the observation log lock wait expired");
+                }
+                sleepForLock(Math.min(LOCK_POLL_MS, remaining));
+                continue;
+            }
+            if (recoverStaleLock(paths, inspection))
+                continue;
+            assertTrustedParents(paths);
+            const remaining = deadline - monotonicNowMs();
+            if (remaining <= 0) {
+                throw new SkillObserverError("OBSERVER_LOCK_TIMEOUT", "the observation log lock wait expired");
+            }
+            sleepForLock(Math.min(LOCK_POLL_MS, remaining));
+        }
+    }
+}
+function assertLockOwnership(lock) {
+    try {
+        assertTrustedParents(lock.paths);
+        const lockStat = lstatSync(lock.path);
+        if (lockStat.isSymbolicLink() || !lockStat.isDirectory()) {
+            throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "the observation log lock changed type");
+        }
+        const ownerStat = lstatSync(lock.ownerPath);
+        if (ownerStat.isSymbolicLink() ||
+            !ownerStat.isFile() ||
+            ownerStat.nlink !== 1 ||
+            (ownerStat.mode & 0o077) !== 0) {
+            throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "the observation log lock owner is unsafe");
+        }
+        if (readFileSync(lock.ownerPath, "utf8") !== lock.token) {
+            throw new SkillObserverError("OBSERVER_LOCK_OWNERSHIP_LOST", "the observation log lock owner changed");
+        }
+    }
+    catch (error) {
+        if (error instanceof SkillObserverError)
+            throw error;
+        throw new SkillObserverError("OBSERVER_LOCK_UNSAFE", "the observation log lock owner could not be verified");
+    }
+}
+function releaseLock(lock) {
+    try {
+        try {
+            lstatSync(lock.path);
+        }
+        catch (error) {
+            if (errnoCode(error) === "ENOENT")
+                return;
+            throw error;
+        }
+        assertLockOwnership(lock);
+        rmSync(lock.path, { recursive: true, force: false });
+    }
+    catch (error) {
+        if (errnoCode(error) === "ENOENT")
+            return;
+        if (error instanceof SkillObserverError)
+            throw error;
+        throw new SkillObserverError("OBSERVER_LOCK_RELEASE_FAILED", "the observation log lock could not be released");
+    }
+}
+function withLock(paths, action) {
+    const lock = acquireLock(paths);
+    try {
+        assertTrustedParents(paths);
+        return action();
+    }
+    finally {
+        releaseLock(lock);
+    }
+}
+export function recordObservation(root, observation) {
+    validateObservation(observation, false);
+    const record = {
+        signal: observation["signal"],
+        skillId: observation["skillId"],
+        observed: flatten(observation["observed"]),
+        proposal: flatten(observation["proposal"]),
+        applied: false,
+    };
+    const line = `${JSON.stringify(record)}\n`;
+    const lineBytes = Buffer.byteLength(line, "utf8");
+    if (lineBytes > MAX_LOG_BYTES) {
+        throw new SkillObserverError("OBSERVER_LOG_SIZE_EXCEEDED", "the observation record exceeds the 1 MiB limit");
+    }
+    const paths = writablePaths(root);
+    let committed = false;
+    let recordStateUnknownError;
+    try {
+        return withLock(paths, () => {
+            const handle = openLogForAppend(paths);
+            try {
+                assertTrustedParents(paths);
+                const existing = readLogBytes(paths.log, handle);
+                parseLog(existing);
+                const separator = existing.byteLength === 0 || existing.at(-1) === 0x0a ? "" : "\n";
+                const appendLine = `${separator}${line}`;
+                const appendBytes = Buffer.byteLength(appendLine, "utf8");
+                const expectedSize = existing.byteLength + appendBytes;
+                if (expectedSize > MAX_LOG_BYTES) {
+                    throw new SkillObserverError("OBSERVER_LOG_SIZE_EXCEEDED", "the observation log would exceed the 1 MiB limit");
+                }
+                const appendBuffer = Buffer.from(appendLine, "utf8");
+                assertTrustedParents(paths);
+                try {
+                    let written = 0;
+                    while (written < appendBuffer.byteLength) {
+                        const count = writeSync(handle, appendBuffer, written, appendBuffer.byteLength - written, null);
+                        if (count <= 0)
+                            throw new Error("the observation log write made no progress");
+                        written += count;
+                    }
+                    fsyncSync(handle);
+                    const after = fstatSync(handle);
+                    assertLogPathIdentity(paths.log, after);
+                    if (after.size > MAX_LOG_BYTES) {
+                        throw new SkillObserverError("OBSERVER_LOG_SIZE_EXCEEDED", "the observation log exceeds the 1 MiB limit");
+                    }
+                    if (after.size !== expectedSize) {
+                        throw new SkillObserverError("OBSERVER_LOG_CONCURRENT_MODIFICATION", "the observation log changed during the append");
+                    }
+                    assertRegularLogHandle(handle);
+                    assertTrustedParents(paths);
+                }
+                catch (error) {
+                    try {
+                        ftruncateSync(handle, existing.byteLength);
+                        fsyncSync(handle);
+                    }
+                    catch {
+                        recordStateUnknownError = new SkillObserverError(OBSERVER_RECORD_STATE_UNKNOWN, "rollback failed; the record state is unknown; read the log before retrying");
+                        throw recordStateUnknownError;
+                    }
+                    if (error instanceof SkillObserverError)
+                        throw error;
+                    throw new SkillObserverError("OBSERVER_LOG_WRITE_FAILED", "the observation log could not be written");
+                }
+                committed = true;
+                return record;
+            }
+            finally {
+                closeSync(handle);
+            }
+        });
+    }
+    catch (error) {
+        if (committed) {
+            throw new SkillObserverError(OBSERVER_RECORD_COMMITTED_CLEANUP_FAILED, "the record was committed, but cleanup failed; read the log before retrying");
+        }
+        if (recordStateUnknownError !== undefined)
+            throw recordStateUnknownError;
+        throw error;
+    }
+}
+export function readObservations(root = process.cwd()) {
+    const paths = readablePaths(root);
+    if (paths === undefined)
+        return [];
+    return withLock(paths, () => {
+        const handle = openLogForRead(paths.log);
+        if (handle === undefined) {
+            assertTrustedParents(paths);
+            return [];
+        }
+        try {
+            assertTrustedParents(paths);
+            return parseLog(readLogBytes(paths.log, handle));
+        }
+        finally {
+            closeSync(handle);
+        }
+    });
+}