@zq-silk/yui 0.15.8 → 0.15.11

package/dist/artifacts/artifactCommitLock.js

@@ -0,0 +1,249 @@
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Short per-Task commit fence for artifact repositories.
+ *
+ * A single meaningful artifact update is: write file(s) → verify scope →
+ * local commit. Two concurrent saves in the same Task repo must not interleave
+ * their `git add`/`commit` steps, or one could sweep the other's staged paths
+ * into the wrong commit, or race the expected-HEAD check. This fence serializes
+ * the commit critical section for one Task.
+ *
+ * Unlike the Project maintenance fence (which guards long operations and fails
+ * fast so the CLI is not blocked), an artifact save is a short operation, so a
+ * contended fence briefly RETRIES before giving up. It is otherwise the same
+ * crash-safe design: an exclusive directory under the Home's `locks/` area
+ * (O_EXCL via mkdir), an owner file recording PID + process start time so a
+ * recycled PID can never pass for the original holder, and reclaim of a stale
+ * (dead-owner) lock.
+ */
+const ARTIFACT_COMMIT_LOCK_TIMEOUT_MS = 5_000;
+const ARTIFACT_COMMIT_LOCK_RETRY_MS = 15;
+/** A lock older than this with a dead owner is reclaimed. */
+const STALE_ARTIFACT_COMMIT_LOCK_AGE_MS = 2_000;
+/**
+ * Raised when a Task's artifact commit fence could not be acquired within the
+ * retry window. The caller made no changes and is safe to retry.
+ */
+export class ArtifactCommitLockedError extends Error {
+    taskId;
+    retryable = true;
+    constructor(taskId) {
+        super(`Another artifact save is in progress for ${taskId}; retry once it finishes.`);
+        this.name = "ArtifactCommitLockedError";
+        this.taskId = taskId;
+    }
+}
+/** Directory of one Task's artifact commit fence, below the Home's locks area. */
+export function artifactCommitLockPath(home, taskId) {
+    return join(home, "locks", "task-artifacts", `${taskId}.lock`);
+}
+/**
+ * Acquire one Task's artifact commit fence. Returns the release function;
+ * callers MUST release on every exit path (try/finally). A live holder is
+ * retried until the timeout, then fails with {@link ArtifactCommitLockedError};
+ * a stale (dead) holder is reclaimed. There is no in-process reentrancy: every
+ * acquisition contends.
+ */
+export function acquireArtifactCommitLock(home, taskId) {
+    const lock = artifactCommitLockPath(home, taskId);
+    mkdirSync(join(home, "locks", "task-artifacts"), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + ARTIFACT_COMMIT_LOCK_TIMEOUT_MS;
+    while (true) {
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+            const ownerIdentity = writeOwnerIdentity(lock);
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                releaseOwnedArtifactCommitLock(lock, ownerIdentity);
+            };
+        }
+        catch (error) {
+            if (!isEexist(error))
+                throw error;
+            reclaimStaleArtifactCommitLock(lock);
+            if (Date.now() >= deadline)
+                throw new ArtifactCommitLockedError(taskId);
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ARTIFACT_COMMIT_LOCK_RETRY_MS);
+        }
+    }
+}
+/** Write this process's owner identity and return the exact bytes recorded. */
+function writeOwnerIdentity(lock) {
+    const identity = `${process.pid}:${processStartIdentity() ?? ""}`;
+    writeFileSync(join(lock, "owner"), `${identity}\n`, { mode: 0o600 });
+    return identity;
+}
+/**
+ * Remove the lock directory only when its owner file still records the exact
+ * identity this handle acquired. A replaced (successor) lock is left intact.
+ */
+function releaseOwnedArtifactCommitLock(lock, ownerIdentity) {
+    let owner;
+    try {
+        owner = readFileSync(join(lock, "owner"), "utf8").trim();
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return; // already gone; nothing to release.
+        throw error;
+    }
+    if (owner !== ownerIdentity)
+        return;
+    rmSync(lock, { recursive: true, force: true });
+}
+/**
+ * Reclaim a stale (dead-owner) lock through a crash-safe compare-and-delete
+ * critical section, serialized by a reclaim lock so two contenders cannot both
+ * delete a successor. Under the reclaim lock we re-read the owner and delete
+ * only when it is still the exact stale instance observed above.
+ */
+function reclaimStaleArtifactCommitLock(lock) {
+    let expectedOwner;
+    try {
+        expectedOwner = readFileSync(join(lock, "owner"), "utf8");
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            throw error;
+        // Ownerless lock: a crash between mkdir and owner publication. Reclaim only
+        // when old enough that the creator is not still initializing.
+        try {
+            if (Date.now() - statSync(lock).mtimeMs < STALE_ARTIFACT_COMMIT_LOCK_AGE_MS)
+                return;
+        }
+        catch (statError) {
+            if (isEnoent(statError))
+                return;
+            throw statError;
+        }
+        expectedOwner = null;
+    }
+    try {
+        if (Date.now() - statSync(lock).mtimeMs < STALE_ARTIFACT_COMMIT_LOCK_AGE_MS)
+            return;
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return;
+        throw error;
+    }
+    if (expectedOwner !== null && lockOwnerIsAlive(lock))
+        return;
+    const reclaimLock = `${lock}.reclaim`;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            mkdirSync(reclaimLock, { mode: 0o700 });
+        }
+        catch (error) {
+            if (!isEexist(error))
+                throw error;
+            if (reclaimOrphanedReclaimLock(reclaimLock))
+                continue;
+            return;
+        }
+        try {
+            writeOwnerIdentity(reclaimLock);
+            let stat;
+            try {
+                stat = statSync(lock);
+            }
+            catch (error) {
+                if (isEnoent(error))
+                    return;
+                throw error;
+            }
+            if (Date.now() - stat.mtimeMs < STALE_ARTIFACT_COMMIT_LOCK_AGE_MS)
+                return;
+            let currentOwner;
+            try {
+                currentOwner = readFileSync(join(lock, "owner"), "utf8");
+            }
+            catch (error) {
+                if (!isEnoent(error))
+                    throw error;
+                if (expectedOwner !== null)
+                    return;
+                currentOwner = null;
+            }
+            if (currentOwner !== expectedOwner)
+                return;
+            if (currentOwner !== null && lockOwnerIsAlive(lock))
+                return;
+            rmSync(lock, { recursive: true, force: true });
+        }
+        finally {
+            rmSync(reclaimLock, { recursive: true, force: true });
+        }
+        return;
+    }
+}
+/**
+ * Reclaim a reclaim-lock directory only when provably orphaned: dead (or
+ * unrecorded) owner AND older than the age bound. Returns true when it removed
+ * the lock (caller retries), false otherwise.
+ */
+function reclaimOrphanedReclaimLock(reclaimLock) {
+    try {
+        if (Date.now() - statSync(reclaimLock).mtimeMs < STALE_ARTIFACT_COMMIT_LOCK_AGE_MS)
+            return false;
+        if (lockOwnerIsAlive(reclaimLock))
+            return false;
+        rmSync(reclaimLock, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        return isEnoent(error);
+    }
+}
+function lockOwnerIsAlive(lock) {
+    let owner;
+    try {
+        owner = readFileSync(join(lock, "owner"), "utf8").trim();
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return false;
+        return true; // Unreadable owner fails closed: treat the fence as held.
+    }
+    const separator = owner.indexOf(":");
+    const pid = Number.parseInt(separator < 0 ? owner : owner.slice(0, separator), 10);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    const recordedIdentity = separator < 0 ? "" : owner.slice(separator + 1);
+    const currentIdentity = processStartIdentity(pid);
+    if (currentIdentity !== undefined) {
+        return recordedIdentity !== "" && currentIdentity === recordedIdentity;
+    }
+    return processIsAlive(pid);
+}
+/** Linux process start time (clock ticks since boot) for a PID; undefined off /proc. */
+function processStartIdentity(pid = process.pid) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        const close = stat.lastIndexOf(")");
+        const fields = stat.slice(close + 2).split(" ");
+        return fields[19] ?? "0"; // field 22: starttime
+    }
+    catch {
+        return undefined;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "EPERM";
+    }
+}
+function isEnoent(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isEexist(error) {
+    return error instanceof Error && "code" in error && error.code === "EEXIST";
+}

package/dist/artifacts/artifactPaths.js

@@ -0,0 +1,151 @@
+import { lstat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+/**
+ * Filesystem layout and path-safety for per-Task artifact repositories.
+ *
+ * At most one local Git repository per Task lives at
+ * `<YUI_HOME>/task-artifacts/<task-id>/`. This location is derived DIRECTLY
+ * from the Home (not through `resolveWorkspaceRoot`, which forbids paths inside
+ * YUI_HOME): artifact repos are deliberately Home-internal working stores, not
+ * delivery workspaces.
+ *
+ * `relativePath` is an artifact's identity. Every path a caller supplies is
+ * validated against traversal (`..`), absolute escape, and symbolic-link
+ * escape before it is used for a filesystem or Git operation. The canonical
+ * form is POSIX (forward-slash) so it doubles as a stable Git pathspec and a
+ * stable identity across platforms.
+ */
+const RESERVED_SEGMENTS = Object.freeze([
+    ".", "..", "__proto__", "prototype", "constructor"
+]);
+/** Root under the Home that holds every Task's artifact repository. */
+export function taskArtifactsRoot(home) {
+    return join(resolve(home), "task-artifacts");
+}
+/**
+ * Absolute path of one Task's artifact repository. The Task id is validated as
+ * a single safe path segment, so a crafted id cannot escape the artifacts root.
+ */
+export function taskArtifactRepoPath(home, taskId) {
+    return join(taskArtifactsRoot(home), safePathSegment(taskId, "Task id"));
+}
+/** Validate one path segment (Task id / directory name). Mirrors safePathSegment in the workspace layer. */
+export function safePathSegment(value, label = "Identity") {
+    const normalized = value.trim();
+    if (normalized.length === 0 ||
+        RESERVED_SEGMENTS.includes(normalized) ||
+        /[\/\\\0]/.test(normalized)) {
+        throw new Error(`${label} is invalid for managed artifact layout.`);
+    }
+    return normalized;
+}
+/**
+ * Validate and canonicalize an artifact `relativePath` to POSIX form. Rejects
+ * absolute paths, empty input, backslashes, control characters, and any `.`,
+ * `..`, empty, or reserved segment. The result is a forward-slash relative path
+ * suitable as both a Git pathspec and a stable identity.
+ *
+ * This is a PURE lexical check; it does not touch the filesystem. Use
+ * {@link resolveContainedArtifactPath} to additionally guard against symbolic
+ * links before a filesystem read or write.
+ */
+export function safeRelativeArtifactPath(relativePath) {
+    if (typeof relativePath !== "string" || relativePath.length === 0) {
+        throw new Error("Artifact relativePath is required.");
+    }
+    if (relativePath.includes("\0")) {
+        throw new Error("Artifact relativePath contains a NUL byte.");
+    }
+    if (relativePath.includes("\\")) {
+        throw new Error("Artifact relativePath must use forward slashes.");
+    }
+    if (isAbsolute(relativePath) || relativePath.startsWith("/")) {
+        throw new Error("Artifact relativePath must be relative.");
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f]/.test(relativePath)) {
+        throw new Error("Artifact relativePath contains control characters.");
+    }
+    // An artifact's identity is a literal path, never a pattern. Reject Git glob
+    // and pathspec-magic metacharacters (`*` `?` `[` `]` `:`) so a relativePath can
+    // never be interpreted as a wildcard that matches OTHER paths, and never carry
+    // pathspec magic like `:(exclude)`. (The managed runner also forces literal
+    // pathspecs, but rejecting them in the identity keeps identities unambiguous.)
+    if (/[*?[\]:]/.test(relativePath)) {
+        throw new Error("Artifact relativePath contains a glob or pathspec metacharacter (*?[]:).");
+    }
+    const segments = relativePath.split("/");
+    for (const segment of segments) {
+        if (segment.length === 0) {
+            throw new Error("Artifact relativePath has an empty path segment.");
+        }
+        if (RESERVED_SEGMENTS.includes(segment)) {
+            throw new Error(`Artifact relativePath has a forbidden segment: ${segment}.`);
+        }
+        // The Git control directory is never a valid artifact location. Reject it
+        // case-insensitively so a case-insensitive filesystem cannot alias into it.
+        if (segment.toLowerCase() === ".git") {
+            throw new Error("Artifact relativePath may not enter the Git control directory.");
+        }
+        if (segment.trim() !== segment) {
+            throw new Error("Artifact relativePath segment has leading or trailing whitespace.");
+        }
+    }
+    return segments.join("/");
+}
+/**
+ * Resolve a validated `relativePath` to an absolute filesystem path inside the
+ * repository, and prove it does not escape through a symbolic link. Every
+ * existing ancestor component (and the target itself, when present) is
+ * `lstat`ed; a symlink anywhere on the path is rejected. Artifact repositories
+ * are created solely by Yui and never legitimately contain symlinks, so this
+ * strict policy blocks read/write-through-symlink escapes without false
+ * positives.
+ *
+ * Returns the absolute path. Does not create anything.
+ */
+export async function resolveContainedArtifactPath(repoRoot, relativePath) {
+    const canonicalRoot = resolve(repoRoot);
+    const safeRelative = safeRelativeArtifactPath(relativePath);
+    const absolute = resolve(canonicalRoot, safeRelative);
+    // Lexical containment: the resolved path must remain within the repo root.
+    const fromRoot = relative(canonicalRoot, absolute);
+    if (fromRoot.length === 0 || fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+        throw new Error("Artifact relativePath escapes its repository.");
+    }
+    // Symlink-escape guard: walk each component from the root down; reject the
+    // first symbolic link. `.git` is never a valid artifact ancestor either.
+    const segments = safeRelative.split("/");
+    let current = canonicalRoot;
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        if (segment === ".git") {
+            throw new Error("Artifact relativePath may not enter the Git control directory.");
+        }
+        current = join(current, segment);
+        const kind = await pathKind(current);
+        if (kind === "symlink") {
+            throw new Error("Artifact relativePath resolves through a symbolic link.");
+        }
+        // An intermediate component that exists but is not a directory is invalid.
+        if (kind === "file" && index < segments.length - 1) {
+            throw new Error("Artifact relativePath descends into a file.");
+        }
+    }
+    return absolute;
+}
+async function pathKind(path) {
+    try {
+        const entry = await lstat(path);
+        if (entry.isSymbolicLink())
+            return "symlink";
+        if (entry.isDirectory())
+            return "directory";
+        return "file";
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}

package/dist/artifacts/gitArtifactRef.js

@@ -0,0 +1,146 @@
+import { openTaskArtifactRepository } from "./taskArtifactRepository.js";
+import { requireCommitId } from "./managedGit.js";
+import { safeRelativeArtifactPath } from "./artifactPaths.js";
+/** Compact string form for reference lists that are plain strings (completion refs). */
+const GIT_ARTIFACT_REF_PREFIX = "git:";
+/**
+ * Validate a {@link GitArtifactRef}'s shape (PURE; no I/O). Safe to call inside
+ * a synchronous DB transaction and inside the synchronous context pipeline.
+ * Returns a normalized copy (canonical POSIX relativePath, lowercased commit).
+ */
+export function validateGitArtifactRef(ref) {
+    if (!ref || typeof ref !== "object")
+        throw new Error("Git artifact ref must be an object.");
+    if (typeof ref.taskId !== "string" || ref.taskId.trim().length === 0) {
+        throw new Error("Git artifact ref requires a taskId.");
+    }
+    const commit = requireCommitId(ref.commit);
+    const relativePath = safeRelativeArtifactPath(ref.relativePath);
+    if (ref.digest !== undefined && !/^[a-f0-9]{64}$/u.test(ref.digest)) {
+        throw new Error("Git artifact ref digest must be a sha256 hex string.");
+    }
+    return Object.freeze({
+        taskId: ref.taskId,
+        commit,
+        relativePath,
+        ...(ref.digest === undefined ? {} : { digest: ref.digest })
+    });
+}
+/** True when a plain string is a commit-pinned artifact reference. */
+export function isGitArtifactRefString(value) {
+    return typeof value === "string" && value.startsWith(GIT_ARTIFACT_REF_PREFIX);
+}
+/**
+ * Format a same-Task pinned reference as `git:<commit>:<relativePath>`. The
+ * Task is implicit (the reference belongs to the referencing Task, e.g. a
+ * completion ref of the completing Task). The digest is omitted: the commit is
+ * the freeze, so the string form is already self-certifying.
+ */
+export function formatGitArtifactRef(ref) {
+    const valid = validateGitArtifactRef(ref);
+    return `${GIT_ARTIFACT_REF_PREFIX}${valid.commit}:${valid.relativePath}`;
+}
+/**
+ * Parse `git:<commit>:<relativePath>` for a given Task. Rejects any malformed
+ * form. PURE; no I/O. `commit` is a full object id and never contains a colon,
+ * so the first colon after the prefix splits commit from path unambiguously.
+ */
+export function parseGitArtifactRef(value, taskId) {
+    if (!isGitArtifactRefString(value)) {
+        throw new Error("Not a commit-pinned artifact reference.");
+    }
+    const body = value.slice(GIT_ARTIFACT_REF_PREFIX.length);
+    const separator = body.indexOf(":");
+    if (separator <= 0 || separator === body.length - 1) {
+        throw new Error("Commit-pinned reference must be git:<commit>:<relativePath>.");
+    }
+    return validateGitArtifactRef({
+        taskId,
+        commit: body.slice(0, separator),
+        relativePath: body.slice(separator + 1)
+    });
+}
+/**
+ * Resolve a pinned reference to its frozen bytes (ASYNC). Reads the exact
+ * commit/path from the Task's local repository and returns bytes + the actual
+ * sha256. When the reference records a `digest`, a mismatch is a drift error —
+ * though for a correctly pinned commit this can only happen if the recorded
+ * digest was wrong, since the commit freezes the bytes.
+ */
+export async function resolveGitArtifact(home, ref) {
+    const valid = validateGitArtifactRef(ref);
+    const repo = openTaskArtifactRepository(home, valid.taskId);
+    if (!repo.exists()) {
+        throw new Error(`Artifact repository is unavailable for ${valid.taskId}.`);
+    }
+    const content = await repo.read(valid.relativePath, valid.commit);
+    if (valid.digest !== undefined && content.digest !== valid.digest) {
+        throw new Error(`Frozen artifact drifted from its recorded digest: ${valid.taskId}@${valid.commit}:${valid.relativePath}.`);
+    }
+    return content;
+}
+/**
+ * Save one file artifact and return its frozen pinned reference (ASYNC).
+ *
+ * This is the primitive behind the `artifact.save` capability: write `bytes`
+ * to `relativePath` in the Task's local repository, commit exactly that path
+ * (one meaningful update = one commit), and return the commit-pinned reference
+ * for the resulting state. The returned reference is self-certifying, so a
+ * caller can record it directly as frozen evidence.
+ */
+export async function saveArtifactFile(home, taskId, input) {
+    const repo = openTaskArtifactRepository(home, taskId);
+    const relativePath = safeRelativeArtifactPath(input.relativePath);
+    const result = await repo.save({
+        files: [{ relativePath, bytes: input.bytes }],
+        message: input.message ?? `save ${relativePath}`,
+        ...(input.expectedHead === undefined ? {} : { expectedHead: input.expectedHead })
+    });
+    // Read back at the resulting commit to record the exact frozen digest.
+    const content = await repo.read(relativePath, result.commit);
+    return validateGitArtifactRef({
+        taskId,
+        commit: result.commit,
+        relativePath: content.relativePath,
+        digest: content.digest
+    });
+}
+export async function readCurrentArtifact(home, taskId, relativePath) {
+    const repo = openTaskArtifactRepository(home, taskId);
+    if (!repo.exists())
+        throw new Error(`Artifact repository is unavailable for ${taskId}.`);
+    return repo.read(safeRelativeArtifactPath(relativePath));
+}
+/** Ordinary listing: tracked artifacts at HEAD (ASYNC, not frozen). Empty when no repo yet. */
+export async function listCurrentArtifacts(home, taskId) {
+    const repo = openTaskArtifactRepository(home, taskId);
+    if (!repo.exists())
+        return [];
+    return repo.list();
+}
+/**
+ * Pin the CURRENT HEAD state of one or more relativePaths into frozen
+ * references (ASYNC). Used at Candidate submission / completion time to capture
+ * exactly what exists now. Fails if any path is not tracked at HEAD.
+ */
+export async function pinCurrentArtifacts(home, taskId, relativePaths) {
+    const repo = openTaskArtifactRepository(home, taskId);
+    if (!repo.exists())
+        throw new Error(`Artifact repository is unavailable for ${taskId}.`);
+    const head = await repo.head();
+    if (head === null)
+        throw new Error(`Artifact repository has no commits for ${taskId}.`);
+    const refs = [];
+    for (const relativePath of relativePaths) {
+        // Reading at the pinned commit both proves the path exists there and yields
+        // the exact digest to record for display/fast verification.
+        const content = await repo.read(safeRelativeArtifactPath(relativePath), head);
+        refs.push(validateGitArtifactRef({
+            taskId,
+            commit: head,
+            relativePath: content.relativePath,
+            digest: content.digest
+        }));
+    }
+    return refs;
+}