stageflow 0.40.0 → 0.44.0

package/dist/runstore/sqlite/migrations/015-evals.js

@@ -0,0 +1,157 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+/**
+ * Eval runs, their cases, results, grades and the author's reviews, plus `runs.origin` so stage runs
+ * started by an eval can be hidden from normal run views. `eval_run_counters` keeps `run_number`
+ * from being reused after an eval run is deleted.
+ */
+export const MIGRATION_015 = {
+    version: 15,
+    name: "015_evals",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        db.exec(`
+ALTER TABLE runs ADD COLUMN origin TEXT;
+CREATE INDEX runs_origin ON runs (origin);
+
+CREATE TABLE eval_runs (
+  eval_run_id TEXT PRIMARY KEY,
+  project_root TEXT NOT NULL,
+  eval_id TEXT NOT NULL,
+  run_number INTEGER NOT NULL,
+  eval_path TEXT NOT NULL,
+  eval_hash TEXT NOT NULL,
+  target_kind TEXT NOT NULL CHECK (target_kind IN ('stage','agent')),
+  target_ref_json TEXT NOT NULL,
+  target_version_hash TEXT NOT NULL,
+  dataset_path TEXT NOT NULL,
+  dataset_hash TEXT NOT NULL,
+  config_json TEXT NOT NULL,
+  config_fingerprint TEXT NOT NULL,
+  config_components_json TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('queued','running','completed','failed','cancelled','budget_stopped')),
+  status_reason TEXT,
+  passed INTEGER,
+  repeats INTEGER NOT NULL,
+  pass_threshold REAL NOT NULL,
+  max_cost_usd REAL NOT NULL,
+  cases_total INTEGER NOT NULL,
+  results_total INTEGER NOT NULL,
+  results_done INTEGER NOT NULL DEFAULT 0,
+  cost_usd REAL NOT NULL DEFAULT 0,
+  engine_name TEXT NOT NULL,
+  engine_version TEXT NOT NULL,
+  stageflow_version TEXT NOT NULL,
+  label TEXT,
+  started_via TEXT NOT NULL CHECK (started_via IN ('console','cli','mcp')),
+  caller_id TEXT,
+  summary_json TEXT,
+  created_at TEXT NOT NULL,
+  started_at TEXT,
+  finished_at TEXT
+);
+CREATE UNIQUE INDEX eval_runs_number ON eval_runs (project_root, eval_id, run_number);
+CREATE INDEX eval_runs_eval ON eval_runs (project_root, eval_id, created_at DESC);
+CREATE INDEX eval_runs_status ON eval_runs (status);
+
+CREATE TABLE eval_run_counters (
+  project_root TEXT NOT NULL,
+  eval_id TEXT NOT NULL,
+  last_number INTEGER NOT NULL,
+  PRIMARY KEY (project_root, eval_id)
+);
+
+CREATE TABLE eval_cases (
+  eval_run_id TEXT NOT NULL REFERENCES eval_runs (eval_run_id) ON DELETE CASCADE,
+  case_id TEXT NOT NULL,
+  position INTEGER NOT NULL,
+  case_json TEXT NOT NULL,
+  PRIMARY KEY (eval_run_id, case_id)
+);
+
+CREATE TABLE eval_results (
+  eval_run_id TEXT NOT NULL REFERENCES eval_runs (eval_run_id) ON DELETE CASCADE,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('completed','stage_failed','needs_input','error','skipped_budget','cancelled')),
+  error_code TEXT,
+  error_message TEXT,
+  stage_run_id TEXT,
+  output_json TEXT,
+  latency_ms INTEGER,
+  cost_usd REAL,
+  tokens_in INTEGER,
+  tokens_out INTEGER,
+  score REAL,
+  passed INTEGER NOT NULL DEFAULT 0,
+  has_grader_errors INTEGER NOT NULL DEFAULT 0,
+  budget_warnings_json TEXT,
+  started_at TEXT,
+  finished_at TEXT,
+  PRIMARY KEY (eval_run_id, case_id, repeat_index),
+  FOREIGN KEY (eval_run_id, case_id) REFERENCES eval_cases (eval_run_id, case_id) ON DELETE CASCADE
+);
+CREATE INDEX eval_results_stage_run ON eval_results (stage_run_id);
+
+CREATE TABLE eval_grades (
+  eval_run_id TEXT NOT NULL,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER NOT NULL,
+  grader_id TEXT NOT NULL,
+  grader_type TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('graded','error')),
+  passed INTEGER,
+  score REAL,
+  raw_value REAL,
+  reason TEXT,
+  details_json TEXT,
+  error_code TEXT,
+  judge_model TEXT,
+  judge_cost_usd REAL,
+  judge_tokens_in INTEGER,
+  judge_tokens_out INTEGER,
+  PRIMARY KEY (eval_run_id, case_id, repeat_index, grader_id),
+  FOREIGN KEY (eval_run_id, case_id, repeat_index) REFERENCES eval_results (eval_run_id, case_id, repeat_index) ON DELETE CASCADE
+);
+
+CREATE TABLE eval_grader_versions (
+  project_root TEXT NOT NULL,
+  eval_id TEXT NOT NULL,
+  grader_id TEXT NOT NULL,
+  grader_hash TEXT NOT NULL,
+  ordinal INTEGER NOT NULL,
+  first_seen_at TEXT NOT NULL,
+  PRIMARY KEY (project_root, eval_id, grader_id, grader_hash)
+);
+
+CREATE TABLE eval_failure_types (
+  project_root TEXT NOT NULL,
+  eval_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (project_root, eval_id, name COLLATE NOCASE)
+);
+
+CREATE TABLE eval_result_reviews (
+  eval_run_id TEXT NOT NULL,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER NOT NULL,
+  label TEXT NOT NULL CHECK (label IN ('pass','fail')),
+  note TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (eval_run_id, case_id, repeat_index),
+  FOREIGN KEY (eval_run_id, case_id, repeat_index) REFERENCES eval_results (eval_run_id, case_id, repeat_index) ON DELETE CASCADE
+);
+
+CREATE TABLE eval_result_tags (
+  eval_run_id TEXT NOT NULL,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER NOT NULL,
+  tag TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (eval_run_id, case_id, repeat_index, tag COLLATE NOCASE),
+  FOREIGN KEY (eval_run_id, case_id, repeat_index) REFERENCES eval_results (eval_run_id, case_id, repeat_index) ON DELETE CASCADE
+);
+`);
+    },
+};

package/dist/runstore/sqlite/migrations/016-eval-subject-ref.d.ts

@@ -0,0 +1,12 @@
+import type Database from "better-sqlite3";
+/**
+ * Agent eval results point at an agent session, not a stage run: `subject_ref` is the root subject id
+ * (stage run id for stage results, agent session id for agent results). `turns` and `tool_call_count`
+ * are agent summaries. Additive; stage rows keep `stage_run_id` and are backfilled.
+ */
+export declare const MIGRATION_016: {
+    version: number;
+    name: string;
+    minStageflowVersion: string;
+    up(db: Database.Database): void;
+};

package/dist/runstore/sqlite/migrations/016-eval-subject-ref.js

@@ -0,0 +1,20 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+/**
+ * Agent eval results point at an agent session, not a stage run: `subject_ref` is the root subject id
+ * (stage run id for stage results, agent session id for agent results). `turns` and `tool_call_count`
+ * are agent summaries. Additive; stage rows keep `stage_run_id` and are backfilled.
+ */
+export const MIGRATION_016 = {
+    version: 16,
+    name: "016_eval_subject_ref",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        db.exec(`
+ALTER TABLE eval_results ADD COLUMN subject_ref TEXT;
+ALTER TABLE eval_results ADD COLUMN turns INTEGER;
+ALTER TABLE eval_results ADD COLUMN tool_call_count INTEGER;
+UPDATE eval_results SET subject_ref = stage_run_id WHERE stage_run_id IS NOT NULL;
+CREATE INDEX eval_results_subject_ref ON eval_results (subject_ref);
+`);
+    },
+};

package/dist/runstore/sqlite/migrations/017-eval-result-suggestions.d.ts

@@ -0,0 +1,11 @@
+import type Database from "better-sqlite3";
+/**
+ * Suggested bucket and failure type per failed eval result, produced on request by a classifier
+ * (`jev` or `judge`). A suggestion becomes a tag only when the author accepts it. Additive.
+ */
+export declare const MIGRATION_017: {
+    version: number;
+    name: string;
+    minStageflowVersion: string;
+    up(db: Database.Database): void;
+};

package/dist/runstore/sqlite/migrations/017-eval-result-suggestions.js

@@ -0,0 +1,36 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+/**
+ * Suggested bucket and failure type per failed eval result, produced on request by a classifier
+ * (`jev` or `judge`). A suggestion becomes a tag only when the author accepts it. Additive.
+ */
+export const MIGRATION_017 = {
+    version: 17,
+    name: "017_eval_result_suggestions",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        db.exec(`
+CREATE TABLE eval_result_suggestions (
+  id TEXT PRIMARY KEY,
+  eval_run_id TEXT NOT NULL,
+  case_id TEXT NOT NULL,
+  repeat_index INTEGER NOT NULL,
+  source TEXT NOT NULL CHECK (source IN ('jev','judge')),
+  bucket TEXT NOT NULL CHECK (bucket IN ('agent_wrong','grader_wrong','case_wrong','unclear')),
+  failure_type TEXT,
+  confidence REAL NOT NULL,
+  probabilities_json TEXT NOT NULL,
+  grader_false_alarms_json TEXT NOT NULL,
+  model TEXT NOT NULL,
+  prompt_version INTEGER NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','accepted','dismissed')),
+  batch_id TEXT NOT NULL,
+  cost_usd REAL NOT NULL DEFAULT 0,
+  state_truncated INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  UNIQUE (eval_run_id, case_id, repeat_index, source),
+  FOREIGN KEY (eval_run_id, case_id, repeat_index) REFERENCES eval_results (eval_run_id, case_id, repeat_index) ON DELETE CASCADE
+);
+CREATE INDEX eval_result_suggestions_run ON eval_result_suggestions (eval_run_id, status);
+`);
+    },
+};

package/dist/runstore/sqlite/migrations/index.js

@@ -13,6 +13,9 @@ import { MIGRATION_011 } from "./011-email-dispatch-key.js";
 import { MIGRATION_012 } from "./012-trigger-fires.js";
 import { MIGRATION_013 } from "./013-agents.js";
 import { MIGRATION_014 } from "./014-agent-deliveries.js";
+import { MIGRATION_015 } from "./015-evals.js";
+import { MIGRATION_016 } from "./016-eval-subject-ref.js";
+import { MIGRATION_017 } from "./017-eval-result-suggestions.js";
 const DEFAULT_MIGRATIONS = [
     MIGRATION_001,
     MIGRATION_002,
@@ -28,6 +31,9 @@ const DEFAULT_MIGRATIONS = [
     MIGRATION_012,
     MIGRATION_013,
     MIGRATION_014,
+    MIGRATION_015,
+    MIGRATION_016,
+    MIGRATION_017,
 ];
 export const CURRENT_SCHEMA_VERSION = DEFAULT_MIGRATIONS[DEFAULT_MIGRATIONS.length - 1].version;
 function throwStoreSchemaTooNew(db, version, maxKnown) {

package/dist/runstore/sqlite/suggestionStore.d.ts

@@ -0,0 +1,14 @@
+import type Database from "better-sqlite3";
+import type { SuggestionInput, SuggestionRow } from "../../evals/triage/types.js";
+/** Inserts or replaces pending suggestions; accepted and dismissed ones are kept. Returns the rows this call wrote. */
+export declare function upsertEvalSuggestions(db: Database.Database, evalRunId: string, inputs: SuggestionInput[]): SuggestionRow[];
+export declare function listEvalSuggestions(db: Database.Database, evalRunId: string, status?: SuggestionRow["status"]): SuggestionRow[];
+export declare function dismissEvalSuggestions(db: Database.Database, evalRunId: string, ids: string[]): number;
+/**
+ * Marks pending suggestions accepted and adds their failure type and `bucket:<bucket>` tags to the result
+ * through `putEvalReview`, keeping tags already there. Returns how many were accepted and how many results gained a tag.
+ */
+export declare function acceptEvalSuggestions(db: Database.Database, evalRunId: string, ids: string[]): {
+    accepted: number;
+    tagged: number;
+};

package/dist/runstore/sqlite/suggestionStore.js

@@ -0,0 +1,132 @@
+import { randomBytes } from "node:crypto";
+import { EvalStoreError } from "../../evals/storeError.js";
+import { BUCKET_TAG_PREFIX } from "../../evals/triage/constants.js";
+import { getEvalReviews, putEvalReview } from "./evalStore.js";
+const now = () => new Date().toISOString();
+function suggestionFromDb(row) {
+    return {
+        id: row.id,
+        evalRunId: row.eval_run_id,
+        caseId: row.case_id,
+        repeatIndex: row.repeat_index,
+        source: row.source,
+        bucket: row.bucket,
+        failureType: row.failure_type,
+        confidence: row.confidence,
+        bucketProbabilities: JSON.parse(row.probabilities_json),
+        graderFalseAlarms: JSON.parse(row.grader_false_alarms_json),
+        model: row.model,
+        promptVersion: row.prompt_version,
+        status: row.status,
+        batchId: row.batch_id,
+        costUsd: row.cost_usd,
+        stateTruncated: row.state_truncated === 1,
+        createdAt: row.created_at,
+    };
+}
+/** Inserts or replaces pending suggestions; accepted and dismissed ones are kept. Returns the rows this call wrote. */
+export function upsertEvalSuggestions(db, evalRunId, inputs) {
+    const written = [];
+    const at = now();
+    db.transaction(() => {
+        for (const input of inputs) {
+            const info = db
+                .prepare(`INSERT INTO eval_result_suggestions
+             (id, eval_run_id, case_id, repeat_index, source, bucket, failure_type, confidence, probabilities_json,
+              grader_false_alarms_json, model, prompt_version, status, batch_id, cost_usd, state_truncated, created_at)
+           VALUES (@id, @eval_run_id, @case_id, @repeat_index, @source, @bucket, @failure_type, @confidence, @probabilities_json,
+              @grader_false_alarms_json, @model, @prompt_version, 'pending', @batch_id, @cost_usd, @state_truncated, @at)
+           ON CONFLICT (eval_run_id, case_id, repeat_index, source) DO UPDATE SET
+             bucket = excluded.bucket, failure_type = excluded.failure_type, confidence = excluded.confidence,
+             probabilities_json = excluded.probabilities_json, grader_false_alarms_json = excluded.grader_false_alarms_json,
+             model = excluded.model, prompt_version = excluded.prompt_version, batch_id = excluded.batch_id,
+             cost_usd = excluded.cost_usd, state_truncated = excluded.state_truncated, created_at = excluded.created_at
+           WHERE eval_result_suggestions.status = 'pending'`)
+                .run({
+                id: `sg_${randomBytes(8).toString("hex")}`,
+                eval_run_id: evalRunId,
+                case_id: input.caseId,
+                repeat_index: input.repeatIndex,
+                source: input.source,
+                bucket: input.bucket,
+                failure_type: input.failureType,
+                confidence: input.confidence,
+                probabilities_json: JSON.stringify(input.bucketProbabilities),
+                grader_false_alarms_json: JSON.stringify(input.graderFalseAlarms),
+                model: input.model,
+                prompt_version: input.promptVersion,
+                batch_id: input.batchId,
+                cost_usd: input.costUsd,
+                state_truncated: input.stateTruncated ? 1 : 0,
+                at,
+            });
+            if (info.changes === 0)
+                continue;
+            const row = db
+                .prepare(`SELECT * FROM eval_result_suggestions WHERE eval_run_id = ? AND case_id = ? AND repeat_index = ? AND source = ?`)
+                .get(evalRunId, input.caseId, input.repeatIndex, input.source);
+            written.push(suggestionFromDb(row));
+        }
+    })();
+    return written;
+}
+export function listEvalSuggestions(db, evalRunId, status) {
+    const rows = (status !== undefined
+        ? db
+            .prepare(`SELECT * FROM eval_result_suggestions WHERE eval_run_id = ? AND status = ? ORDER BY case_id, repeat_index, source`)
+            .all(evalRunId, status)
+        : db
+            .prepare(`SELECT * FROM eval_result_suggestions WHERE eval_run_id = ? ORDER BY case_id, repeat_index, source`)
+            .all(evalRunId));
+    return rows.map(suggestionFromDb);
+}
+export function dismissEvalSuggestions(db, evalRunId, ids) {
+    let changed = 0;
+    db.transaction(() => {
+        for (const id of ids) {
+            changed += db
+                .prepare(`UPDATE eval_result_suggestions SET status = 'dismissed' WHERE eval_run_id = ? AND id = ? AND status = 'pending'`)
+                .run(evalRunId, id).changes;
+        }
+    })();
+    return changed;
+}
+/**
+ * Marks pending suggestions accepted and adds their failure type and `bucket:<bucket>` tags to the result
+ * through `putEvalReview`, keeping tags already there. Returns how many were accepted and how many results gained a tag.
+ */
+export function acceptEvalSuggestions(db, evalRunId, ids) {
+    let accepted = 0;
+    let tagged = 0;
+    db.transaction(() => {
+        for (const id of ids) {
+            const found = db
+                .prepare(`SELECT * FROM eval_result_suggestions WHERE eval_run_id = ? AND id = ? AND status = 'pending'`)
+                .get(evalRunId, id);
+            if (found === undefined)
+                continue;
+            const suggestion = suggestionFromDb(found);
+            const add = [
+                ...(suggestion.failureType !== null ? [suggestion.failureType] : []),
+                `${BUCKET_TAG_PREFIX}${suggestion.bucket}`,
+            ];
+            const have = getEvalReviews(db, evalRunId).find((r) => r.caseId === suggestion.caseId && r.repeatIndex === suggestion.repeatIndex)?.tags ?? [];
+            const haveKeys = new Set(have.map((t) => t.toLowerCase()));
+            const fresh = add.filter((t) => !haveKeys.has(t.toLowerCase()));
+            if (fresh.length > 0) {
+                try {
+                    putEvalReview(db, evalRunId, suggestion.caseId, suggestion.repeatIndex, { tags: [...have, ...fresh] });
+                    tagged += 1;
+                }
+                catch (err) {
+                    if (err instanceof EvalStoreError && err.code === "EVAL_TAGS_ON_PASSED_RESULT")
+                        continue;
+                    throw err;
+                }
+            }
+            db.prepare(`UPDATE eval_result_suggestions SET status = 'accepted' WHERE id = ?`).run(id);
+            accepted += 1;
+        }
+    })();
+    return { accepted, tagged };
+}

package/dist/runstore/workspaceLayout.js

@@ -1,6 +1,7 @@
 import { access, lstat, mkdir, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { globalCredentialRoot } from "../project/globalHome.js";
+import { buildArtifactListedPath } from "../runtime/artifactPath.js";
 import { STAGEFLOW_AGENT_AUTH_PATH_ENV } from "../runtime/credentialBinding.js";
 import { SF_STAGE_WORKER } from "../runtime/stageWorkerProtocol.js";
 export { stageDir } from "./paths.js";
@@ -186,7 +187,11 @@ export function resolveArtifactTarget(runWorkspaceDir, stageId, attempt, relativ
         path.isAbsolute(relativeToArtifacts)) {
         throw new Error("path escapes the stage artifacts directory");
     }
-    const runRelativePath = path.posix.join("stages", stageId, "attempts", String(attempt), "artifacts", ...relativeToArtifacts.split(path.sep));
+    const runRelativePath = buildArtifactListedPath({
+        stageId,
+        attempt,
+        relative: relativeToArtifacts.split(path.sep).join("/"),
+    });
     return {
         absolutePath: resolved,
         runRelativePath,

package/dist/runtime/artifactDiskInspect.d.ts

@@ -0,0 +1,14 @@
+export type ArtifactDiskFileType = "file" | "directory" | "symlink" | "other" | "missing";
+export type ArtifactDiskPresence = {
+    file_type: ArtifactDiskFileType;
+    /** Lexical absolute path under root when the walk reached a leaf. */
+    absolutePath?: string;
+    /** From lstat when `file_type` is `file`. */
+    size_bytes?: number;
+};
+/**
+ * Closed-posture walk of `relativePath` under `rootDir`: lstat every segment,
+ * classify symlink / missing / file / directory / other. Does not follow
+ * symlinks. Escape attempts are `missing`. Non-ENOENT errors propagate.
+ */
+export declare function inspectArtifactUnderRoot(rootDir: string, relativePath: string): Promise<ArtifactDiskPresence>;

package/dist/runtime/artifactDiskInspect.js

@@ -0,0 +1,52 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Closed-posture walk of `relativePath` under `rootDir`: lstat every segment,
+ * classify symlink / missing / file / directory / other. Does not follow
+ * symlinks. Escape attempts are `missing`. Non-ENOENT errors propagate.
+ */
+export async function inspectArtifactUnderRoot(rootDir, relativePath) {
+    const target = path.resolve(rootDir, relativePath);
+    const relative = path.relative(rootDir, target);
+    if (relative === "" ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return { file_type: "missing" };
+    }
+    try {
+        const segments = relative.split(path.sep).filter((segment) => segment !== "");
+        let current = rootDir;
+        let stats;
+        for (const segment of segments) {
+            current = path.join(current, segment);
+            stats = await lstat(current);
+            if (stats.isSymbolicLink()) {
+                return { file_type: "symlink", absolutePath: current };
+            }
+            if (current !== target && !stats.isDirectory()) {
+                return { file_type: "other", absolutePath: current };
+            }
+        }
+        if (stats === undefined) {
+            return { file_type: "missing" };
+        }
+        if (stats.isDirectory()) {
+            return { file_type: "directory", absolutePath: current };
+        }
+        if (!stats.isFile()) {
+            return { file_type: "other", absolutePath: current };
+        }
+        return {
+            file_type: "file",
+            absolutePath: current,
+            size_bytes: stats.size,
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { file_type: "missing" };
+        }
+        throw error;
+    }
+}

package/dist/runtime/artifactPath.d.ts

@@ -0,0 +1,24 @@
+/** Parts of a run-relative artifact path under `stages/.../artifacts/`. */
+export type ArtifactPathParts = {
+    stageId: string;
+    attempt: number;
+    relative: string;
+};
+export type ArtifactPathMode = {
+    kind: "grantable";
+} | {
+    kind: "current_attempt";
+    stageId: string;
+    attempt: number;
+};
+export declare function attemptArtifactsPrefix(stageId: string, attempt: number): string;
+export declare function buildArtifactListedPath(parts: ArtifactPathParts): string;
+/**
+ * Accept a listed artifact path under a mode.
+ * - `grantable`: full run-relative path to a prior stage/attempt artifact file.
+ * - `current_attempt`: that attempt's run-relative prefix, or a bare path under
+ *   its artifacts dir; foreign `stages/...` paths are rejected.
+ */
+export declare function acceptArtifactListedPath(listedPath: string, mode: ArtifactPathMode): ArtifactPathParts | undefined;
+export declare function parseArtifactListedPath(listedPath: string): ArtifactPathParts | undefined;
+export declare function isGrantableArtifactPath(listedPath: string): boolean;

package/dist/runtime/artifactPath.js

@@ -0,0 +1,84 @@
+import path from "node:path";
+export function attemptArtifactsPrefix(stageId, attempt) {
+    return path.posix.join("stages", stageId, "attempts", String(attempt), "artifacts");
+}
+export function buildArtifactListedPath(parts) {
+    const relative = parts.relative.replace(/\\/g, "/");
+    const segments = relative.split("/").filter((segment) => segment.length > 0);
+    return path.posix.join("stages", parts.stageId, "attempts", String(parts.attempt), "artifacts", ...segments);
+}
+function parseStrictGrantable(listedPath) {
+    if (typeof listedPath !== "string" || listedPath.length === 0)
+        return undefined;
+    const posix = listedPath.replace(/\\/g, "/");
+    if (path.isAbsolute(listedPath) || path.posix.isAbsolute(posix))
+        return undefined;
+    if (posix.includes("\0") || posix.includes(".."))
+        return undefined;
+    const parts = posix.split("/").filter((part) => part.length > 0);
+    if (parts.length < 6)
+        return undefined;
+    if (parts[0] !== "stages" || parts[2] !== "attempts" || parts[4] !== "artifacts") {
+        return undefined;
+    }
+    const attemptRaw = parts[3];
+    if (!/^\d+$/.test(attemptRaw))
+        return undefined;
+    const attempt = Number(attemptRaw);
+    if (!Number.isInteger(attempt) || attempt < 1)
+        return undefined;
+    const relative = parts.slice(5).join("/");
+    if (relative.length === 0)
+        return undefined;
+    return {
+        stageId: parts[1],
+        attempt,
+        relative,
+    };
+}
+/**
+ * Accept a listed artifact path under a mode.
+ * - `grantable`: full run-relative path to a prior stage/attempt artifact file.
+ * - `current_attempt`: that attempt's run-relative prefix, or a bare path under
+ *   its artifacts dir; foreign `stages/...` paths are rejected.
+ */
+export function acceptArtifactListedPath(listedPath, mode) {
+    if (mode.kind === "grantable") {
+        return parseStrictGrantable(listedPath);
+    }
+    if (typeof listedPath !== "string" || listedPath.length === 0) {
+        return undefined;
+    }
+    const posixListed = listedPath.replace(/\\/g, "/");
+    if (path.isAbsolute(listedPath) || path.posix.isAbsolute(posixListed)) {
+        return undefined;
+    }
+    const prefix = attemptArtifactsPrefix(mode.stageId, mode.attempt);
+    if (posixListed === prefix || posixListed === `${prefix}/`) {
+        return undefined;
+    }
+    if (posixListed.startsWith(`${prefix}/`)) {
+        const relative = posixListed.slice(prefix.length + 1);
+        if (relative.length === 0)
+            return undefined;
+        return {
+            stageId: mode.stageId,
+            attempt: mode.attempt,
+            relative,
+        };
+    }
+    if (posixListed.startsWith("stages/")) {
+        return undefined;
+    }
+    return {
+        stageId: mode.stageId,
+        attempt: mode.attempt,
+        relative: posixListed,
+    };
+}
+export function parseArtifactListedPath(listedPath) {
+    return parseStrictGrantable(listedPath);
+}
+export function isGrantableArtifactPath(listedPath) {
+    return acceptArtifactListedPath(listedPath, { kind: "grantable" }) !== undefined;
+}