@litfamily/litopencode 1.0.0 → 1.0.2

package/dist/skill-observer.js

@@ -1,1154 +0,0 @@
-// Durable store for skill-improvement observations.
-//
-// The capability's whole value rests on one restraint: it proposes, and something with judgement
-// decides. A tool that edited skills from its own inferences would compound its mistakes silently,
-// and the skill corpus would drift away from anything a reviewer approved. So every record here
-// carries `applied: false`, and nothing in this module opens a skill file for writing.
-//
-// Observations are text the session did not author -- a user's correction quoted back, a pattern
-// noticed in a transcript. That text is stored as data: bounded, single-line, credential-free, and
-// never interpreted. An observation asking to rewrite every skill is a curiosity to record, not an
-// instruction to follow.
-import { createHash, randomUUID } from "node:crypto";
-import { closeSync, constants, ftruncateSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, readFileSync, readlinkSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { performance } from "node:perf_hooks";
-import { TextDecoder } from "node:util";
-import { containsIngressSecret, containsSecret } from "./secret-shapes.js";
-import { runtimeDirectoryName } from "./state.js";
-import { sameStableDirectoryIdentity, sameStableStatIdentity, stableStatIdentity } from "./stable-identity.js";
-/** The three signals worth capturing. A fourth needs a contract revision, not a free-text value. */
-export const OBSERVER_SIGNALS = Object.freeze(["correction", "repetition", "coverage-gap"]);
-export const OBSERVER_RECORD_COMMITTED_CLEANUP_FAILED = "OBSERVER_RECORD_COMMITTED_CLEANUP_FAILED";
-export const OBSERVER_RECORD_STATE_UNKNOWN = "OBSERVER_RECORD_STATE_UNKNOWN";
-const allowedFields = Object.freeze(["signal", "skillId", "observed", "proposal"]);
-const persistedFields = Object.freeze([...allowedFields, "applied"]);
-const textCeiling = 1000;
-const skillIdShape = /^[a-z][a-z0-9-]{0,63}$/u;
-export const OBSERVER_LOG_MAX_BYTES = 1_048_576;
-const observerLockWaitMs = 2_000;
-const observerLockPollMs = 10;
-const observerLockStaleMs = 30_000;
-const observerLockOwnerMaxBytes = 512;
-const observerLockDirectoryName = "litopencode-skill-observer";
-const observerLockOwnerTempShape = /^\.owner-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
-const noFollow = constants.O_NOFOLLOW ?? 0;
-const lockWaitState = new Int32Array(new SharedArrayBuffer(4));
-export class SkillObserverError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.name = "SkillObserverError";
-        this.code = code;
-    }
-}
-export function observationLogPath(root) {
-    return path.join(path.resolve(root), runtimeDirectoryName, "skill-observer", "observations.jsonl");
-}
-export function observerLockPath(root) {
-    const projectRoot = path.resolve(root);
-    const projectKey = createHash("sha256").update(projectRoot, "utf8").digest("hex");
-    return path.join(tmpdir(), `${observerLockDirectoryName}-${projectKey}.lock`);
-}
-// One line, bounded, control characters removed. A newline would break the record format and is the
-// simplest way to forge a second entry, so whitespace is collapsed rather than preserved. Format
-// controls are zero-width: replacing one with a space would both misrender the text and hide a
-// credential split mid-token from the flattened-surface secret check, so they are stripped instead.
-function flatten(value) {
-    return value
-        .replace(/\p{Cf}/gu, "")
-        .replace(/\p{Cc}/gu, " ")
-        .replace(/\s+/gu, " ")
-        .trim()
-        .slice(0, textCeiling);
-}
-function errorCode(error) {
-    if (typeof error !== "object" || error === null || !("code" in error))
-        return undefined;
-    const code = error.code;
-    return typeof code === "string" ? code : undefined;
-}
-function observerError(code, message) {
-    throw new SkillObserverError(code, message);
-}
-function committedCleanupError() {
-    return observerError(OBSERVER_RECORD_COMMITTED_CLEANUP_FAILED, "the observation record was committed, but cleanup failed; read the log before retrying");
-}
-function unknownRecordStateError() {
-    return observerError(OBSERVER_RECORD_STATE_UNKNOWN, "rollback failed; the observation record state is unknown; read the log before retrying");
-}
-function isUnknownRecordState(error) {
-    return error instanceof SkillObserverError && error.code === OBSERVER_RECORD_STATE_UNKNOWN;
-}
-function containsObserverSecret(value, ingress) {
-    return ingress ? containsIngressSecret(value) : containsSecret(value);
-}
-function isWithinRoot(root, target) {
-    const relative = path.relative(root, target);
-    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
-}
-function safePaths(root) {
-    let projectRoot;
-    try {
-        projectRoot = path.resolve(root);
-    }
-    catch {
-        return observerError("OBSERVER_PATH_UNSAFE", "the observation path is unsafe");
-    }
-    const logPath = observationLogPath(root);
-    const parentPath = path.dirname(logPath);
-    if (!isWithinRoot(projectRoot, logPath) || !isWithinRoot(projectRoot, parentPath)) {
-        return observerError("OBSERVER_PATH_UNSAFE", "the observation path escapes the requested root");
-    }
-    return { projectRoot, parentPath, logPath };
-}
-function assertDirectory(directoryPath) {
-    let stat;
-    try {
-        stat = lstatSync(directoryPath);
-    }
-    catch {
-        return observerError("OBSERVER_PATH_UNSAFE", "an observation parent path cannot be inspected safely");
-    }
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        observerError("OBSERVER_PATH_UNSAFE", "an observation parent path is not a regular directory");
-    }
-}
-function isTrustedSystemAlias(candidate) {
-    if (process.platform !== "darwin")
-        return false;
-    const targets = {
-        "/etc": "/private/etc",
-        "/tmp": "/private/tmp",
-        "/var": "/private/var"
-    };
-    try {
-        return path.resolve(path.dirname(candidate), readlinkSync(candidate)) === targets[candidate];
-    }
-    catch {
-        return false;
-    }
-}
-function assertSafeRequestedRootParents(projectRoot) {
-    const filesystemRoot = path.parse(projectRoot).root;
-    let parent = path.dirname(projectRoot);
-    while (true) {
-        try {
-            const stat = lstatSync(parent);
-            if (stat.isSymbolicLink()) {
-                if (!isTrustedSystemAlias(parent))
-                    observerError("OBSERVER_PATH_UNSAFE", "the requested root has a symlinked parent");
-            }
-            else if (!stat.isDirectory()) {
-                observerError("OBSERVER_PATH_UNSAFE", "the requested root parent is not a regular directory");
-            }
-        }
-        catch (error) {
-            if (errorCode(error) !== "ENOENT") {
-                observerError("OBSERVER_PATH_UNSAFE", "the requested root parent cannot be inspected safely");
-            }
-        }
-        if (parent === filesystemRoot)
-            return;
-        const next = path.dirname(parent);
-        if (next === parent)
-            observerError("OBSERVER_PATH_UNSAFE", "the requested root parent does not exist safely");
-        parent = next;
-    }
-}
-function ensureSafeDirectoryTree(projectRoot, targetDirectory, create) {
-    assertSafeRequestedRootParents(projectRoot);
-    let rootExists = true;
-    try {
-        const stat = lstatSync(projectRoot);
-        if (stat.isSymbolicLink() || !stat.isDirectory()) {
-            observerError("OBSERVER_PATH_UNSAFE", "the requested root is not a regular directory");
-        }
-    }
-    catch (error) {
-        if (errorCode(error) !== "ENOENT") {
-            observerError("OBSERVER_PATH_UNSAFE", "the requested root cannot be inspected safely");
-        }
-        rootExists = false;
-    }
-    if (!rootExists) {
-        if (!create)
-            return false;
-        try {
-            mkdirSync(projectRoot, { recursive: true, mode: 0o700 });
-        }
-        catch {
-            observerError("OBSERVER_PATH_UNSAFE", "the requested root cannot be created safely");
-        }
-        assertDirectory(projectRoot);
-    }
-    let current = projectRoot;
-    const relative = path.relative(projectRoot, targetDirectory);
-    for (const segment of relative.split(path.sep).filter(Boolean)) {
-        current = path.join(current, segment);
-        let stat;
-        try {
-            stat = lstatSync(current);
-        }
-        catch (error) {
-            if (errorCode(error) !== "ENOENT") {
-                observerError("OBSERVER_PATH_UNSAFE", "an observation parent path cannot be inspected safely");
-            }
-            stat = undefined;
-        }
-        if (stat !== undefined) {
-            if (stat.isSymbolicLink() || !stat.isDirectory()) {
-                observerError("OBSERVER_PATH_UNSAFE", "an observation parent path is not a regular directory");
-            }
-            continue;
-        }
-        if (stat === undefined) {
-            if (!create)
-                return false;
-            try {
-                mkdirSync(current, { mode: 0o700 });
-            }
-            catch (error) {
-                if (errorCode(error) !== "EEXIST") {
-                    observerError("OBSERVER_PATH_UNSAFE", "an observation parent path cannot be created safely");
-                }
-            }
-            assertDirectory(current);
-        }
-    }
-    return true;
-}
-function assertRegularUnlinkedFile(stat) {
-    if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) {
-        observerError("OBSERVER_LOG_UNSAFE", "the observation log must be a regular file with one link");
-    }
-    if ((stat.mode & 0o077) !== 0) {
-        observerError("OBSERVER_LOG_PERMISSIONS_UNSAFE", "the observation log must not be group or world accessible");
-    }
-}
-function existingLogStat(logPath) {
-    try {
-        const stat = lstatSync(logPath);
-        assertRegularUnlinkedFile(stat);
-        return stat;
-    }
-    catch (error) {
-        if (error instanceof SkillObserverError)
-            throw error;
-        if (errorCode(error) === "ENOENT")
-            return undefined;
-        observerError("OBSERVER_LOG_UNSAFE", "the observation log cannot be inspected safely");
-    }
-}
-function directoryIdentity(directoryPath) {
-    let stat;
-    try {
-        stat = lstatSync(directoryPath);
-    }
-    catch {
-        observerError("OBSERVER_PATH_UNSAFE", "the observation parent path cannot be inspected safely");
-    }
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        observerError("OBSERVER_PATH_UNSAFE", "the observation parent path is not a regular directory");
-    }
-    return { ...stableStatIdentity(stat), nlink: stat.nlink };
-}
-function sameFile(left, right) {
-    return left.dev === right.dev && left.ino === right.ino && left.nlink === right.nlink;
-}
-function sameStableFile(left, right) {
-    return sameStableStatIdentity(stableStatIdentity(left), stableStatIdentity(right)) && left.nlink === right.nlink;
-}
-function sameDirectory(left, right) {
-    return sameStableDirectoryIdentity(stableStatIdentity(left), stableStatIdentity(right));
-}
-function fileState(stat) {
-    return {
-        dev: stat.dev,
-        ino: stat.ino,
-        nlink: stat.nlink,
-        size: stat.size,
-        ctimeMs: stat.ctimeMs,
-        mtimeMs: stat.mtimeMs,
-        birthtimeMs: stat.birthtimeMs
-    };
-}
-function sameFileState(left, right) {
-    return sameFile(left, right)
-        && left.size === right.size
-        && left.ctimeMs === right.ctimeMs
-        && left.mtimeMs === right.mtimeMs
-        && left.birthtimeMs === right.birthtimeMs;
-}
-function openLog(logPath, flags, mode) {
-    const creates = (flags & constants.O_CREAT) !== 0;
-    let descriptor;
-    let created = false;
-    try {
-        descriptor = openSync(logPath, creates ? flags | constants.O_EXCL : flags, mode);
-        created = creates;
-    }
-    catch (error) {
-        if (error instanceof SkillObserverError)
-            throw error;
-        if (!creates || errorCode(error) !== "EEXIST") {
-            if (errorCode(error) === "ENOENT")
-                return undefined;
-            observerError("OBSERVER_LOG_UNSAFE", "the observation log cannot be opened safely");
-        }
-        try {
-            descriptor = openSync(logPath, flags, mode);
-        }
-        catch (fallbackError) {
-            if (fallbackError instanceof SkillObserverError)
-                throw fallbackError;
-            if (errorCode(fallbackError) === "ENOENT")
-                return undefined;
-            observerError("OBSERVER_LOG_UNSAFE", "the observation log cannot be opened safely");
-        }
-    }
-    if (descriptor === undefined)
-        return undefined;
-    return { descriptor, created };
-}
-function removeCreatedLog(logPath, identity) {
-    let pathStat;
-    try {
-        pathStat = lstatSync(logPath);
-    }
-    catch (error) {
-        if (errorCode(error) === "ENOENT")
-            return;
-        observerError("OBSERVER_LOG_UNSAFE", "the newly created observation log cannot be inspected safely");
-    }
-    if (pathStat.isSymbolicLink() || !pathStat.isFile() || !sameStableFile(identity, pathStat)) {
-        observerError("OBSERVER_LOG_UNSAFE", "the newly created observation log cannot be removed safely");
-    }
-    try {
-        unlinkSync(logPath);
-    }
-    catch {
-        observerError("OBSERVER_LOG_UNSAFE", "the newly created observation log cannot be removed safely");
-    }
-    try {
-        lstatSync(logPath);
-    }
-    catch (error) {
-        if (errorCode(error) === "ENOENT")
-            return;
-        observerError("OBSERVER_LOG_UNSAFE", "the newly created observation log was not removed safely");
-    }
-    observerError("OBSERVER_LOG_UNSAFE", "the newly created observation log was not removed safely");
-}
-function assertLogHandle(projectRoot, parentPath, logPath, handle) {
-    if (!ensureSafeDirectoryTree(projectRoot, parentPath, false)) {
-        observerError("OBSERVER_PATH_UNSAFE", "the observation parent path is unavailable");
-    }
-    if (!sameDirectory(handle.parentIdentity, directoryIdentity(parentPath))) {
-        observerError("OBSERVER_PATH_UNSAFE", "the observation parent path changed during log access");
-    }
-    const descriptorStat = fstatSync(handle.descriptor);
-    assertRegularUnlinkedFile(descriptorStat);
-    if (!sameFile(handle.identity, descriptorStat)) {
-        observerError("OBSERVER_LOG_UNSAFE", "the observation log descriptor changed identity");
-    }
-    if (!ensureSafeDirectoryTree(projectRoot, parentPath, false)) {
-        observerError("OBSERVER_PATH_UNSAFE", "the observation parent path changed during log access");
-    }
-    const pathStat = existingLogStat(logPath);
-    if (pathStat === undefined || !sameStableFile(pathStat, descriptorStat)) {
-        observerError("OBSERVER_LOG_UNSAFE", "the observation log path changed identity");
-    }
-}
-function openValidatedLog(projectRoot, parentPath, logPath, flags, mode) {
-    if (!ensureSafeDirectoryTree(projectRoot, parentPath, false))
-        return undefined;
-    const parentIdentity = directoryIdentity(parentPath);
-    const opened = openLog(logPath, flags, mode);
-    if (opened === undefined)
-        return undefined;
-    let handle;
-    let cleanupError;
-    try {
-        const descriptorStat = fstatSync(opened.descriptor);
-        handle = {
-            descriptor: opened.descriptor,
-            identity: descriptorStat,
-            parentIdentity,
-            created: opened.created
-        };
-        assertRegularUnlinkedFile(descriptorStat);
-        assertLogHandle(projectRoot, parentPath, logPath, handle);
-        return handle;
-    }
-    catch (error) {
-        if (handle?.created) {
-            try {
-                removeCreatedLog(logPath, handle.identity);
-            }
-            catch (removalError) {
-                cleanupError = removalError;
-            }
-        }
-        try {
-            closeSync(opened.descriptor);
-        }
-        catch (closeError) {
-            cleanupError ??= closeError;
-        }
-        if (cleanupError instanceof SkillObserverError)
-            throw cleanupError;
-        if (cleanupError !== undefined) {
-            observerError("OBSERVER_LOG_UNSAFE", "the newly created observation log cleanup failed");
-        }
-        throw error;
-    }
-}
-function malformedLog() {
-    return observerError("OBSERVER_LOG_MALFORMED", "the observation log contains malformed JSONL");
-}
-function validateObservation(value, persisted) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        throw new SkillObserverError("OBSERVER_SHAPE_INVALID", "an observation must be an object");
-    }
-    const candidate = value;
-    const fields = persisted ? persistedFields : allowedFields;
-    const unknown = Object.keys(candidate).filter((key) => !fields.includes(key));
-    if (unknown.length > 0) {
-        throw new SkillObserverError("OBSERVER_FIELD_UNKNOWN", "the observation contains an unknown field");
-    }
-    if (persisted) {
-        const missing = persistedFields.filter((field) => !Object.hasOwn(candidate, field));
-        if (missing.length > 0) {
-            throw new SkillObserverError("OBSERVER_FIELD_MISSING", `missing observation field: ${missing.join(", ")}`);
-        }
-    }
-    if (!OBSERVER_SIGNALS.includes(candidate.signal)) {
-        throw new SkillObserverError("OBSERVER_SIGNAL_UNKNOWN", `signal must be one of ${OBSERVER_SIGNALS.join(", ")}`);
-    }
-    if (typeof candidate.skillId !== "string" || !skillIdShape.test(candidate.skillId)) {
-        throw new SkillObserverError("OBSERVER_SKILL_ID_INVALID", "skillId must be a lowercase skill identifier");
-    }
-    for (const field of ["observed", "proposal"]) {
-        const value = candidate[field];
-        if (typeof value !== "string" || value.trim() === "") {
-            throw new SkillObserverError("OBSERVER_TEXT_MISSING", `${field} must be non-empty text`);
-        }
-        // Normalization runs before detection: format-control characters can reconstruct a credential
-        // the raw text split, two ways. Stripping them rejoins a token split mid-word (xoxb<Cf>-...),
-        // while replacing them with a space restores a pattern that needs the space (bearer<Cf>TOKEN).
-        // Both surfaces are checked so neither split evades, and the full field is refused. The
-        // offending value is never echoed: an error message is one more place a secret can land.
-        const flattened = flatten(value);
-        const spaced = value.replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/gu, " ").trim();
-        if (containsObserverSecret(value, !persisted) ||
-            containsObserverSecret(flattened, !persisted) ||
-            containsObserverSecret(spaced, !persisted)) {
-            throw new SkillObserverError("OBSERVER_SECRET_REFUSED", `${field} looks like it carries a credential and was refused before any write`);
-        }
-        if (flattened.length === 0) {
-            throw new SkillObserverError("OBSERVER_TEXT_MISSING", `${field} must contain usable text`);
-        }
-        if (persisted && flattened !== value) {
-            throw new SkillObserverError("OBSERVER_TEXT_INVALID", `${field} is not a canonical observation value`);
-        }
-    }
-    if (persisted && candidate.applied !== false) {
-        throw new SkillObserverError("OBSERVER_APPLIED_INVALID", "applied must be the boolean false");
-    }
-}
-function hasDuplicateJsonObjectKeys(text) {
-    let index = 0;
-    function skipWhitespace() {
-        while (/\s/u.test(text[index] ?? ""))
-            index += 1;
-    }
-    function parseString() {
-        if (text[index] !== '"')
-            throw new Error("expected JSON string");
-        const start = index;
-        index += 1;
-        while (index < text.length) {
-            const character = text[index];
-            index += 1;
-            if (character === "\\") {
-                index += 1;
-            }
-            else if (character === '"') {
-                return JSON.parse(text.slice(start, index));
-            }
-        }
-        throw new Error("unterminated JSON string");
-    }
-    function parsePrimitive() {
-        while (index < text.length && !",]}".includes(text[index] ?? ""))
-            index += 1;
-    }
-    function parseValue() {
-        skipWhitespace();
-        if (text[index] === '"') {
-            parseString();
-            return false;
-        }
-        if (text[index] === "{")
-            return parseObject();
-        if (text[index] === "[")
-            return parseArray();
-        parsePrimitive();
-        return false;
-    }
-    function parseObject() {
-        index += 1;
-        skipWhitespace();
-        const keys = new Set();
-        let duplicate = false;
-        if (text[index] === "}") {
-            index += 1;
-            return false;
-        }
-        while (index < text.length) {
-            const key = parseString();
-            if (keys.has(key))
-                duplicate = true;
-            keys.add(key);
-            skipWhitespace();
-            if (text[index] !== ":")
-                throw new Error("expected JSON object separator");
-            index += 1;
-            if (parseValue())
-                duplicate = true;
-            skipWhitespace();
-            if (text[index] === "}") {
-                index += 1;
-                return duplicate;
-            }
-            if (text[index] !== ",")
-                throw new Error("expected JSON object delimiter");
-            index += 1;
-            skipWhitespace();
-        }
-        throw new Error("unterminated JSON object");
-    }
-    function parseArray() {
-        index += 1;
-        skipWhitespace();
-        let duplicate = false;
-        if (text[index] === "]") {
-            index += 1;
-            return false;
-        }
-        while (index < text.length) {
-            if (parseValue())
-                duplicate = true;
-            skipWhitespace();
-            if (text[index] === "]") {
-                index += 1;
-                return duplicate;
-            }
-            if (text[index] !== ",")
-                throw new Error("expected JSON array delimiter");
-            index += 1;
-            skipWhitespace();
-        }
-        throw new Error("unterminated JSON array");
-    }
-    try {
-        const duplicate = parseValue();
-        skipWhitespace();
-        return index !== text.length || duplicate;
-    }
-    catch {
-        return false;
-    }
-}
-function parseLog(rawBytes) {
-    if (rawBytes.length > OBSERVER_LOG_MAX_BYTES) {
-        observerError("OBSERVER_LOG_SIZE_EXCEEDED", "the observation log exceeds its 1 MiB limit");
-    }
-    let raw;
-    try {
-        raw = new TextDecoder("utf-8", { fatal: true }).decode(rawBytes);
-    }
-    catch {
-        return malformedLog();
-    }
-    const records = [];
-    if (raw === "")
-        return records;
-    const lines = raw.endsWith("\n") ? raw.slice(0, -1).split("\n") : raw.split("\n");
-    for (const line of lines) {
-        if (line.trim() === "")
-            return malformedLog();
-        let parsed;
-        try {
-            parsed = JSON.parse(line);
-            if (hasDuplicateJsonObjectKeys(line)) {
-                throw new SkillObserverError("OBSERVER_LOG_MALFORMED", "duplicate JSON object keys are not allowed");
-            }
-            validateObservation(parsed, true);
-        }
-        catch (error) {
-            if (error instanceof SkillObserverError && error.code === "OBSERVER_LOG_SIZE_EXCEEDED")
-                throw error;
-            return malformedLog();
-        }
-        records.push(parsed);
-    }
-    return records;
-}
-function readLog(handle) {
-    const beforeReadStat = fstatSync(handle.descriptor);
-    assertRegularUnlinkedFile(beforeReadStat);
-    const beforeRead = fileState(beforeReadStat);
-    if (!sameFile(handle.identity, beforeRead)) {
-        observerError("OBSERVER_LOG_UNSAFE", "the observation log descriptor changed identity");
-    }
-    if (typeof beforeRead.size === "number" && beforeRead.size > OBSERVER_LOG_MAX_BYTES) {
-        observerError("OBSERVER_LOG_SIZE_EXCEEDED", "the observation log exceeds its 1 MiB limit");
-    }
-    const bytes = readFileSync(handle.descriptor);
-    const afterReadStat = fstatSync(handle.descriptor);
-    assertRegularUnlinkedFile(afterReadStat);
-    const afterRead = fileState(afterReadStat);
-    if (!sameFileState(beforeRead, afterRead) || bytes.length !== beforeRead.size) {
-        observerError("OBSERVER_LOG_UNSAFE", "the observation log changed during the read");
-    }
-    return { bytes, records: parseLog(bytes), identity: beforeRead };
-}
-function writeFully(descriptor, bytes) {
-    let offset = 0;
-    while (offset < bytes.length) {
-        const remaining = bytes.length - offset;
-        const written = writeSync(descriptor, bytes, offset, remaining);
-        if (!Number.isSafeInteger(written) || written < 1 || written > remaining) {
-            observerError("OBSERVER_WRITE_FAILED", "the observation log write returned an invalid byte count");
-        }
-        offset += written;
-    }
-}
-function appendLog(projectRoot, parentPath, logPath, handle, before, priorLength, contents) {
-    const descriptor = handle.descriptor;
-    const expectedLength = priorLength + Buffer.byteLength(contents, "utf8");
-    const after = fstatSync(descriptor);
-    assertRegularUnlinkedFile(after);
-    if (!sameFile(before, after)) {
-        observerError("OBSERVER_LOG_UNSAFE", "the observation log changed identity before it was written");
-    }
-    if (typeof after.size !== "number" || after.size !== priorLength) {
-        observerError("OBSERVER_LOG_UNSAFE", "the observation log changed size before it was written");
-    }
-    try {
-        writeFully(descriptor, Buffer.from(contents, "utf8"));
-        fsyncSync(descriptor);
-        const afterWrite = fstatSync(descriptor);
-        assertRegularUnlinkedFile(afterWrite);
-        if (!sameFile(before, afterWrite) || afterWrite.size !== expectedLength) {
-            observerError("OBSERVER_LOG_UNSAFE", "the observation log changed identity or size after the write");
-        }
-        assertLogHandle(projectRoot, parentPath, logPath, handle);
-    }
-    catch (error) {
-        try {
-            ftruncateSync(descriptor, priorLength);
-        }
-        catch {
-            unknownRecordStateError();
-        }
-        try {
-            fsyncSync(descriptor);
-        }
-        catch {
-            unknownRecordStateError();
-        }
-        if (error instanceof SkillObserverError)
-            throw error;
-        observerError("OBSERVER_WRITE_FAILED", "the observation log write failed");
-    }
-}
-function waitForLock(milliseconds) {
-    Atomics.wait(lockWaitState, 0, 0, milliseconds);
-}
-function lockDeadline() {
-    return performance.now() + observerLockWaitMs;
-}
-function waitForLockUntil(deadline) {
-    const remaining = deadline - performance.now();
-    if (remaining <= 0) {
-        observerError("OBSERVER_LOCK_TIMEOUT", "the observation lock wait exceeded its bounded limit");
-    }
-    waitForLock(Math.min(observerLockPollMs, Math.max(1, remaining)));
-}
-function processIsAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return errorCode(error) !== "ESRCH";
-    }
-}
-function readLockOwner(ownerPath) {
-    let stat;
-    try {
-        stat = lstatSync(ownerPath);
-    }
-    catch (error) {
-        if (errorCode(error) === "ENOENT")
-            return { status: "ownerless" };
-        observerError("OBSERVER_LOCK_UNSAFE", "the observation lock owner cannot be inspected safely");
-    }
-    if (stat.isSymbolicLink() ||
-        !stat.isFile() ||
-        stat.nlink !== 1 ||
-        (stat.mode & 0o077) !== 0 ||
-        stat.size > observerLockOwnerMaxBytes) {
-        return { status: "invalid" };
-    }
-    let raw;
-    try {
-        raw = readFileSync(ownerPath, "utf8");
-    }
-    catch (error) {
-        if (errorCode(error) === "ENOENT")
-            return { status: "changed" };
-        return { status: "invalid" };
-    }
-    let finalStat;
-    try {
-        finalStat = lstatSync(ownerPath);
-    }
-    catch (error) {
-        if (errorCode(error) === "ENOENT")
-            return { status: "changed" };
-        return { status: "invalid" };
-    }
-    if (finalStat.isSymbolicLink() || !finalStat.isFile() || !sameStableFile(stat, finalStat)) {
-        return { status: "changed" };
-    }
-    if (raw === "" || Buffer.byteLength(raw, "utf8") > observerLockOwnerMaxBytes) {
-        return { status: "invalid" };
-    }
-    try {
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== "object" ||
-            parsed === null ||
-            Array.isArray(parsed) ||
-            typeof parsed.token !== "string" ||
-            parsed.token.length === 0 ||
-            parsed.token.length > 128 ||
-            !Number.isSafeInteger(parsed.pid) ||
-            (parsed.pid) <= 0) {
-            return { status: "invalid" };
-        }
-        return {
-            status: "valid",
-            token: parsed.token,
-            pid: parsed.pid
-        };
-    }
-    catch {
-        return { status: "invalid" };
-    }
-}
-function readLockSnapshot(lockPath) {
-    let stat;
-    try {
-        stat = lstatSync(lockPath);
-    }
-    catch (error) {
-        if (errorCode(error) === "ENOENT")
-            return undefined;
-        observerError("OBSERVER_LOCK_UNSAFE", "the observation lock cannot be inspected safely");
-    }
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        observerError("OBSERVER_LOCK_UNSAFE", "the observation lock must be a regular directory");
-    }
-    return { stat, owner: readLockOwner(path.join(lockPath, "owner")) };
-}
-function sameLockGeneration(left, right) {
-    return sameDirectory(left.stat, right.stat);
-}
-function sameLockOwner(left, right) {
-    if (left.status !== right.status)
-        return false;
-    if (left.status === "changed")
-        return false;
-    if (left.status !== "valid" || right.status !== "valid")
-        return true;
-    return left.token === right.token && left.pid === right.pid;
-}
-function lockAgeIsStale(stat) {
-    try {
-        const mtimeMs = typeof stat.mtimeMs === "bigint" ? Number(stat.mtimeMs) : stat.mtimeMs;
-        return Date.now() - mtimeMs >= observerLockStaleMs;
-    }
-    catch {
-        return false;
-    }
-}
-function lockCanBeRecovered(snapshot) {
-    if (snapshot.owner.status === "invalid") {
-        observerError("OBSERVER_LOCK_UNSAFE", "the observation lock owner metadata is malformed");
-    }
-    if (snapshot.owner.status === "changed")
-        return false;
-    if (snapshot.owner.status === "valid")
-        return !processIsAlive(snapshot.owner.pid);
-    return lockAgeIsStale(snapshot.stat);
-}
-function restoreMovedLock(lockPath, movedPath) {
-    try {
-        lstatSync(lockPath);
-        observerError("OBSERVER_LOCK_UNSAFE", "the observation lock changed during recovery");
-    }
-    catch (error) {
-        if (error instanceof SkillObserverError)
-            throw error;
-        if (errorCode(error) !== "ENOENT") {
-            observerError("OBSERVER_LOCK_UNSAFE", "the observation lock could not be restored safely");
-        }
-    }
-    try {
-        renameSync(movedPath, lockPath);
-    }
-    catch {
-        observerError("OBSERVER_LOCK_UNSAFE", "the observation lock could not be restored safely");
-    }
-}
-function removeMovedLock(movedPath, owner) {
-    let entries;
-    try {
-        entries = readdirSync(movedPath, { withFileTypes: true });
-    }
-    catch {
-        observerError("OBSERVER_LOCK_UNSAFE", "the retired observation lock cannot be inspected safely");
-    }
-    const temporaryOwners = owner === "ownerless"
-        ? entries.filter((entry) => observerLockOwnerTempShape.test(entry.name))
-        : [];
-    if ((owner === "ownerless" && entries.length !== temporaryOwners.length) ||
-        (owner === "owned" && entries.length !== 1) ||
-        (owner === "owned" && (entries[0]?.name !== "owner" ||
-            entries[0]?.isSymbolicLink() ||
-            !entries[0]?.isFile()))) {
-        observerError("OBSERVER_LOCK_UNSAFE", "the retired observation lock contains unexpected entries");
-    }
-    for (const entry of temporaryOwners) {
-        if (entry.isSymbolicLink() || !entry.isFile()) {
-            observerError("OBSERVER_LOCK_UNSAFE", "the retired observation lock owner cannot be removed safely");
-        }
-        let stat;
-        try {
-            stat = lstatSync(path.join(movedPath, entry.name));
-        }
-        catch {
-            observerError("OBSERVER_LOCK_UNSAFE", "the retired observation lock owner cannot be inspected safely");
-        }
-        if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0) {
-            observerError("OBSERVER_LOCK_UNSAFE", "the retired observation lock owner cannot be removed safely");
-        }
-        try {
-            unlinkSync(path.join(movedPath, entry.name));
-        }
-        catch {
-            observerError("OBSERVER_LOCK_UNSAFE", "the retired observation lock owner could not be removed safely");
-        }
-    }
-    if (owner === "owned") {
-        try {
-            unlinkSync(path.join(movedPath, "owner"));
-        }
-        catch {
-            observerError("OBSERVER_LOCK_UNSAFE", "the retired observation lock owner could not be removed safely");
-        }
-    }
-    try {
-        rmSync(movedPath, { force: true, recursive: true });
-    }
-    catch {
-        observerError("OBSERVER_LOCK_UNSAFE", "the retired observation lock could not be removed safely");
-    }
-}
-function tryRecoverStaleLock(lockPath) {
-    const observed = readLockSnapshot(lockPath);
-    if (observed === undefined || !lockCanBeRecovered(observed))
-        return false;
-    const movedPath = `${lockPath}.abandoned-${randomUUID()}`;
-    try {
-        renameSync(lockPath, movedPath);
-    }
-    catch (error) {
-        if (errorCode(error) === "ENOENT")
-            return false;
-        observerError("OBSERVER_LOCK_UNSAFE", "the stale observation lock could not be retired safely");
-    }
-    const moved = readLockSnapshot(movedPath);
-    if (moved === undefined ||
-        !sameLockGeneration(observed, moved) ||
-        !sameLockOwner(observed.owner, moved.owner) ||
-        !lockCanBeRecovered(moved)) {
-        if (moved !== undefined && moved.owner.status === "invalid") {
-            observerError("OBSERVER_LOCK_UNSAFE", "the retired observation lock owner metadata is malformed");
-        }
-        restoreMovedLock(lockPath, movedPath);
-        return false;
-    }
-    removeMovedLock(movedPath, moved.owner.status === "ownerless" ? "ownerless" : "owned");
-    return true;
-}
-function removeCreatedLock(lockPath, expected) {
-    const movedPath = `${lockPath}.failed-${randomUUID()}`;
-    try {
-        renameSync(lockPath, movedPath);
-    }
-    catch (error) {
-        if (errorCode(error) === "ENOENT")
-            return;
-        observerError("OBSERVER_LOCK_UNSAFE", "the failed observation lock could not be retired safely");
-    }
-    const moved = readLockSnapshot(movedPath);
-    if (moved === undefined || !sameDirectory(expected, moved.stat) || moved.owner.status !== "ownerless") {
-        restoreMovedLock(lockPath, movedPath);
-        observerError("OBSERVER_LOCK_UNSAFE", "the failed observation lock changed during cleanup");
-    }
-    removeMovedLock(movedPath, "ownerless");
-}
-function releaseLock(lockPath, token) {
-    const movedPath = `${lockPath}.released-${randomUUID()}`;
-    try {
-        renameSync(lockPath, movedPath);
-    }
-    catch {
-        observerError("OBSERVER_LOCK_UNSAFE", "the observation lock ownership could not be proved");
-    }
-    const owner = readLockOwner(path.join(movedPath, "owner"));
-    if (owner.status !== "valid" || owner.token !== token) {
-        restoreMovedLock(lockPath, movedPath);
-        observerError("OBSERVER_LOCK_UNSAFE", "the observation lock ownership could not be proved");
-    }
-    try {
-        removeMovedLock(movedPath, "owned");
-    }
-    catch (error) {
-        try {
-            restoreMovedLock(lockPath, movedPath);
-        }
-        catch {
-            // Leave the retired lock in place when restoration cannot be proved.
-        }
-        throw error;
-    }
-}
-function lockIsHeld(lockPath) {
-    try {
-        const stat = lstatSync(lockPath);
-        if (stat.isSymbolicLink() || !stat.isDirectory()) {
-            observerError("OBSERVER_LOCK_UNSAFE", "the observation lock must be a regular directory");
-        }
-        return true;
-    }
-    catch (error) {
-        if (errorCode(error) === "ENOENT")
-            return false;
-        observerError("OBSERVER_LOCK_UNSAFE", "the observation lock cannot be inspected safely");
-    }
-}
-function waitUntilObserverLockAvailable(lockPath, legacyLockPath, deadline) {
-    while (true) {
-        if (lockIsHeld(legacyLockPath)) {
-            waitForLockUntil(deadline);
-            continue;
-        }
-        if (!lockIsHeld(lockPath))
-            return;
-        if (tryRecoverStaleLock(lockPath))
-            continue;
-        waitForLockUntil(deadline);
-    }
-}
-function withObserverLock(projectRoot, parentPath, logPath, deadline, operation) {
-    // Keep the lock outside the mutable state tree. A state-directory ancestor can be replaced
-    // between its safety check and lock creation, so a lock below that tree would follow the swap.
-    const lockPath = observerLockPath(projectRoot);
-    const legacyLockPath = `${logPath}.lock`;
-    const ownerPath = path.join(lockPath, "owner");
-    const token = randomUUID();
-    while (true) {
-        let createdLock = false;
-        let createdLockIdentity;
-        let ownerCreated = false;
-        try {
-            if (!ensureSafeDirectoryTree(projectRoot, parentPath, false)) {
-                observerError("OBSERVER_PATH_UNSAFE", "the observation parent path is unavailable");
-            }
-            if (lockIsHeld(legacyLockPath)) {
-                waitForLockUntil(deadline);
-                continue;
-            }
-            if (lockIsHeld(lockPath)) {
-                if (tryRecoverStaleLock(lockPath))
-                    continue;
-                waitForLockUntil(deadline);
-                continue;
-            }
-            try {
-                mkdirSync(lockPath, { mode: 0o700 });
-                createdLock = true;
-                createdLockIdentity = directoryIdentity(lockPath);
-            }
-            catch (error) {
-                if (errorCode(error) !== "EEXIST") {
-                    observerError("OBSERVER_LOCK_UNSAFE", "the observation lock cannot be created safely");
-                }
-            }
-            if (!createdLock) {
-                if (tryRecoverStaleLock(lockPath))
-                    continue;
-                waitForLockUntil(deadline);
-                continue;
-            }
-            const ownerTempPath = path.join(lockPath, `.owner-${randomUUID()}`);
-            const descriptor = openSync(ownerTempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow, 0o600);
-            try {
-                writeFileSync(descriptor, Buffer.from(`${JSON.stringify({ token, pid: process.pid })}\n`, "utf8"));
-            }
-            finally {
-                closeSync(descriptor);
-            }
-            renameSync(ownerTempPath, ownerPath);
-            ownerCreated = true;
-            if (!ensureSafeDirectoryTree(projectRoot, parentPath, false)) {
-                observerError("OBSERVER_PATH_UNSAFE", "the observation parent path changed during lock creation");
-            }
-            break;
-        }
-        catch (error) {
-            if (createdLock) {
-                if (ownerCreated) {
-                    try {
-                        releaseLock(lockPath, token);
-                    }
-                    catch {
-                        // Leave an unproven lock in place.
-                    }
-                }
-                else {
-                    try {
-                        if (createdLockIdentity === undefined) {
-                            observerError("OBSERVER_LOCK_UNSAFE", "the created observation lock identity is unavailable");
-                        }
-                        removeCreatedLock(lockPath, createdLockIdentity);
-                    }
-                    catch {
-                        // Leave an unproven lock in place.
-                    }
-                }
-            }
-            if (error instanceof SkillObserverError)
-                throw error;
-            observerError("OBSERVER_LOCK_UNSAFE", "the observation lock cannot be acquired safely");
-        }
-    }
-    let operationError;
-    try {
-        return operation();
-    }
-    catch (error) {
-        operationError = error;
-        throw error;
-    }
-    finally {
-        try {
-            releaseLock(lockPath, token);
-        }
-        catch (error) {
-            if (!isUnknownRecordState(operationError))
-                throw error;
-        }
-    }
-}
-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 { projectRoot, parentPath, logPath } = safePaths(root);
-    if (!ensureSafeDirectoryTree(projectRoot, parentPath, true)) {
-        observerError("OBSERVER_PATH_UNSAFE", "the observation parent path is unavailable");
-    }
-    const deadline = lockDeadline();
-    waitUntilObserverLockAvailable(observerLockPath(projectRoot), `${logPath}.lock`, deadline);
-    let handle;
-    let committed = false;
-    let primaryError;
-    try {
-        return withObserverLock(projectRoot, parentPath, logPath, deadline, () => {
-            const opened = openValidatedLog(projectRoot, parentPath, logPath, constants.O_RDWR | constants.O_CREAT | constants.O_APPEND | noFollow, 0o600);
-            if (opened === undefined) {
-                observerError("OBSERVER_LOG_UNSAFE", "the observation log cannot be opened safely");
-            }
-            handle = opened;
-            assertLogHandle(projectRoot, parentPath, logPath, opened);
-            const existing = readLog(opened);
-            const line = `${JSON.stringify(record)}\n`;
-            const separator = existing.bytes.length > 0 && existing.bytes[existing.bytes.length - 1] !== 0x0a ? "\n" : "";
-            const appendContents = `${separator}${line}`;
-            const recordBytes = Buffer.byteLength(line, "utf8");
-            if (recordBytes > OBSERVER_LOG_MAX_BYTES) {
-                observerError("OBSERVER_RECORD_TOO_LARGE", "the new observation exceeds the 1 MiB limit");
-            }
-            if (existing.bytes.length + Buffer.byteLength(appendContents, "utf8") > OBSERVER_LOG_MAX_BYTES) {
-                observerError("OBSERVER_LOG_SIZE_EXCEEDED", "the observation log would exceed its 1 MiB limit");
-            }
-            assertLogHandle(projectRoot, parentPath, logPath, opened);
-            appendLog(projectRoot, parentPath, logPath, opened, existing.identity, existing.bytes.length, appendContents);
-            committed = true;
-            return record;
-        });
-    }
-    catch (error) {
-        primaryError = error;
-        if (committed)
-            committedCleanupError();
-        throw error;
-    }
-    finally {
-        try {
-            if (handle !== undefined)
-                closeSync(handle.descriptor);
-        }
-        catch (error) {
-            if (committed)
-                committedCleanupError();
-            if (!isUnknownRecordState(primaryError))
-                throw error;
-        }
-    }
-}
-export function readObservations(root) {
-    const { projectRoot, parentPath, logPath } = safePaths(root);
-    if (!ensureSafeDirectoryTree(projectRoot, parentPath, false))
-        return [];
-    if (existingLogStat(logPath) === undefined)
-        return [];
-    const handle = openValidatedLog(projectRoot, parentPath, logPath, constants.O_RDONLY | noFollow);
-    if (handle === undefined) {
-        observerError("OBSERVER_LOG_UNSAFE", "the observation log disappeared before it could be opened");
-    }
-    try {
-        return withObserverLock(projectRoot, parentPath, logPath, lockDeadline(), () => {
-            assertLogHandle(projectRoot, parentPath, logPath, handle);
-            const records = readLog(handle).records;
-            assertLogHandle(projectRoot, parentPath, logPath, handle);
-            return records;
-        });
-    }
-    finally {
-        closeSync(handle.descriptor);
-    }
-}