@litfamily/litcodex 1.0.1 → 1.0.2

package/marketplace/plugins/litcodex/components/lit-loop/dist/skill-observer.js

@@ -1,946 +0,0 @@
-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);
-        }
-    });
-}