voratiq 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/commands/reduce/targets.js

@@ -137,7 +137,12 @@ async function assertVerificationTargetEligible(input) {
     if (record.status === "aborted") {
         throw new CliError(`Verification session \`${target.id}\` did not complete.`, [`Status: \`${record.status}\`.`], ["Re-run `voratiq verify` to generate a complete artifact set."]);
     }
-    const missing = await findMissingVerificationArtifacts(root, record.methods);
+    const artifactMethods = record.methods.filter((method) => typeof method.artifactPath === "string" &&
+        method.artifactPath.trim().length > 0);
+    if (artifactMethods.length === 0) {
+        throw new CliError(`Verification session \`${target.id}\` has no reduction-ready artifacts.`, [], ["Re-run `voratiq verify` to generate at least one durable artifact."]);
+    }
+    const missing = await findMissingVerificationArtifacts(root, artifactMethods);
     if (missing.length > 0) {
         throw new CliError(`Verification session \`${target.id}\` is missing required artifacts.`, missing.map((path) => `Missing: \`${path}\`.`), ["Re-run `voratiq verify` to regenerate verification artifacts."]);
     }
@@ -162,7 +167,11 @@ async function assertReductionTargetEligibleInternal(input) {
     if (record.status !== "succeeded") {
         throw new CliError(`Reduction session \`${target.id}\` did not complete.`, [`Status: \`${record.status}\`.`], ["Re-run `voratiq reduce` to generate a complete artifact set."]);
     }
-    const missing = await findMissingReductionArtifacts(root, record.reducers);
+    const succeededReducers = record.reducers.filter((reducer) => reducer.status === "succeeded" && typeof reducer.outputPath === "string");
+    if (succeededReducers.length === 0) {
+        throw new CliError(`Reduction session \`${target.id}\` has no successful reduction artifacts.`, [], ["Re-run `voratiq reduce` to regenerate reduction artifacts."]);
+    }
+    const missing = await findMissingReductionArtifacts(root, succeededReducers);
     if (missing.length > 0) {
         throw new CliError(`Reduction session \`${target.id}\` is missing required artifacts.`, missing.map((path) => `Missing: \`${path}\`.`), ["Re-run `voratiq reduce` to regenerate reduction artifacts."]);
     }

package/dist/commands/root-launcher/command.js

@@ -87,7 +87,9 @@ async function setupRootLauncher(options) {
         workspaceAutoInitMode: "when-missing",
     });
     if (context.workspaceAutoInitialized) {
-        writeLauncherNotice(writeOutput, renderWorkspaceAutoInitializedNotice());
+        writeLauncherNotice(writeOutput, renderWorkspaceAutoInitializedNotice(), {
+            leadingNewline: true,
+        });
     }
     const diagnostics = loadDiagnostics({ root: context.root });
     assertEnabledAgents(diagnostics);
@@ -104,9 +106,7 @@ function assertEnabledAgents(diagnostics) {
     if (diagnostics.enabledAgents.length > 0) {
         return;
     }
-    throw new CliError("No enabled agents found.", [], [
-        "Add agents to `.voratiq/agents.yaml` or run `voratiq init` to set up your workspace.",
-    ]);
+    throw new CliError("No enabled agents found.", [], ["Run `voratiq doctor --fix` to repair workspace setup."]);
 }
 function buildLauncherAvailability(diagnostics) {
     const issuesByAgentId = new Map();
@@ -144,7 +144,7 @@ async function promptForLaunchPlan(options) {
             writeOutput,
         });
     if (availability.launchable.length === 1) {
-        writeLauncherNotice(writeOutput, renderRootLauncherSingleAgentScreen({
+        writeLauncherScreen(writeOutput, renderRootLauncherSingleAgentScreen({
             selected: formatAgentLabel(selected.entry),
             unavailable: availability.unavailable.map((agent) => ({
                 label: formatAgentLabel(agent.entry),
@@ -156,7 +156,7 @@ async function promptForLaunchPlan(options) {
 }
 async function promptForAgentSelection(options) {
     const { launchable, unavailable, prompt, writeOutput } = options;
-    writeLauncherNotice(writeOutput, renderRootLauncherSelectionScreen({
+    writeLauncherScreen(writeOutput, renderRootLauncherSelectionScreen({
         launchable: launchable.map((agent) => ({
             label: formatAgentLabel(agent.entry),
         })),
@@ -206,6 +206,12 @@ function writeLauncherNotice(writeOutput, message, options = {}) {
         leadingNewline: options.leadingNewline ?? false,
     });
 }
+function writeLauncherScreen(writeOutput, message) {
+    writeOutput({
+        body: message.trimEnd(),
+        leadingNewline: false,
+    });
+}
 async function finalizeLaunchResult(selected, launchResult) {
     if (!launchResult.ok) {
         throw new CliError(`Failed to launch ${formatAgentLabel(selected.entry)}.`, [launchResult.failure.message]);

package/dist/commands/run/command.d.ts

@@ -4,6 +4,7 @@ import type { RunProgressRenderer } from "../../render/transcripts/run.js";
 export interface RunCommandInput {
     root: string;
     runsFilePath: string;
+    specsFilePath?: string;
     specAbsolutePath: string;
     specDisplayPath: string;
     agentIds?: readonly string[];

package/dist/commands/run/command.js

@@ -21,7 +21,7 @@ import { validateAndPrepare } from "./validation.js";
  * Execute a complete run: validate inputs, prepare workspace, execute agents, and finalize report.
  */
 export async function executeRunCommand(input) {
-    const { root, runsFilePath, specAbsolutePath, specDisplayPath, agentIds, agentOverrideFlag, profileName, maxParallel: requestedMaxParallel, extraContextFiles = [], renderer, } = input;
+    const { root, runsFilePath, specsFilePath, specAbsolutePath, specDisplayPath, agentIds, agentOverrideFlag, profileName, maxParallel: requestedMaxParallel, extraContextFiles = [], renderer, } = input;
     const resolution = resolveStageCompetitors({
         root,
         stageId: "run",
@@ -33,6 +33,8 @@ export async function executeRunCommand(input) {
     const validation = await validateAndPrepare({
         root,
         specAbsolutePath,
+        specDisplayPath,
+        specsFilePath,
         resolvedAgentIds: resolution.agentIds,
         maxParallel: requestedMaxParallel,
     });
@@ -50,6 +52,7 @@ export async function executeRunCommand(input) {
         runsFilePath,
         runId,
         specDisplayPath,
+        specTarget: validation.specTarget,
         baseRevisionSha: validation.baseRevisionSha,
         repoDisplayPath,
         createdAt,

package/dist/commands/run/record-init.d.ts

@@ -1,9 +1,11 @@
 import type { RunRecordInitResult } from "../../domain/run/competition/phases.js";
+import type { RunSpecTarget } from "../../domain/run/model/types.js";
 export interface RecordInitInput {
     readonly root: string;
     readonly runsFilePath: string;
     readonly runId: string;
     readonly specDisplayPath: string;
+    readonly specTarget?: RunSpecTarget;
     readonly baseRevisionSha: string;
     readonly repoDisplayPath: string;
     readonly createdAt: string;

package/dist/commands/run/record-init.js

@@ -5,11 +5,12 @@ import { cleanupRunWorkspace } from "../../workspace/cleanup.js";
  * Initialize and persist the initial run record.
  */
 export async function initializeRunRecord(input) {
-    const { root, runsFilePath, runId, specDisplayPath, baseRevisionSha, repoDisplayPath, createdAt, startedAt, runRoot, extraContext, extraContextMetadata, } = input;
+    const { root, runsFilePath, runId, specDisplayPath, specTarget, baseRevisionSha, repoDisplayPath, createdAt, startedAt, runRoot, extraContext, extraContextMetadata, } = input;
     const initialRecord = {
         runId,
         spec: {
             path: normalizePathForDisplay(specDisplayPath),
+            target: specTarget,
         },
         extraContext,
         extraContextMetadata,

package/dist/commands/run/spec-provenance.d.ts

@@ -0,0 +1,37 @@
+import type { RunSpecTarget } from "../../domain/run/model/types.js";
+interface ParsedVoratiqFrontmatter {
+    readonly bodyContent: string;
+    readonly source?: ParsedVoratiqSourceMetadata;
+    readonly invalidProvenance?: Extract<RunSpecTarget, {
+        kind: "file";
+    }>["provenance"];
+}
+interface ParsedVoratiqSourceMetadata {
+    readonly sessionId: string;
+    readonly agentId: string;
+}
+export interface ResolveRunSpecTargetInput {
+    root: string;
+    specDisplayPath: string;
+    specsFilePath?: string;
+    specAbsolutePath?: string;
+}
+export interface LoadRunSpecInputResult {
+    readonly specContent: string;
+    readonly specTarget: RunSpecTarget;
+}
+/**
+ * Load run spec content, stripping only Voratiq-owned frontmatter before prompt construction.
+ */
+export declare function loadRunSpecInput(input: ResolveRunSpecTargetInput & {
+    specAbsolutePath: string;
+}): Promise<LoadRunSpecInputResult>;
+/**
+ * Resolve a run's spec input to its upstream session identity when the
+ * provided spec path is a generated spec artifact or a descendant that
+ * carries Voratiq-owned provenance metadata.
+ */
+export declare function resolveRunSpecTarget(input: ResolveRunSpecTargetInput & {
+    parsedFrontmatter?: ParsedVoratiqFrontmatter;
+}): Promise<RunSpecTarget>;
+export {};

package/dist/commands/run/spec-provenance.js

@@ -0,0 +1,384 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { load } from "js-yaml";
+import { z } from "zod";
+import { agentIdSchema } from "../../configs/agents/types.js";
+import { readSpecRecords } from "../../domain/spec/persistence/adapter.js";
+import { pathExists } from "../../utils/fs.js";
+import { normalizePathForDisplay } from "../../utils/path.js";
+const FRONTMATTER_PATTERN = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/u;
+const TOP_LEVEL_VORATIQ_BLOCK_PATTERN = /^voratiq\s*:/mu;
+const voratiqFrontmatterSourceSchema = z
+    .object({
+    operator: z.literal("spec"),
+    sessionId: z.string().min(1),
+    agentId: agentIdSchema,
+})
+    .strict();
+/**
+ * Load run spec content, stripping only Voratiq-owned frontmatter before prompt construction.
+ */
+export async function loadRunSpecInput(input) {
+    const rawSpecContent = await readFile(input.specAbsolutePath, "utf8");
+    const parsedFrontmatter = parseVoratiqFrontmatter(rawSpecContent);
+    return {
+        specContent: parsedFrontmatter.bodyContent,
+        specTarget: await resolveRunSpecTarget({
+            ...input,
+            parsedFrontmatter,
+        }),
+    };
+}
+/**
+ * Resolve a run's spec input to its upstream session identity when the
+ * provided spec path is a generated spec artifact or a descendant that
+ * carries Voratiq-owned provenance metadata.
+ */
+export async function resolveRunSpecTarget(input) {
+    const { root, specDisplayPath, specsFilePath, specAbsolutePath } = input;
+    const normalizedSpecPath = normalizePathForDisplay(specDisplayPath);
+    const parsedFrontmatter = input.parsedFrontmatter ??
+        (specAbsolutePath
+            ? parseVoratiqFrontmatter(await readFile(specAbsolutePath, "utf8"))
+            : undefined);
+    if (!specsFilePath || !(await pathExists(specsFilePath))) {
+        return parsedFrontmatter?.invalidProvenance
+            ? {
+                kind: "file",
+                provenance: parsedFrontmatter.invalidProvenance,
+            }
+            : { kind: "file" };
+    }
+    try {
+        const exactMatch = await readExactSpecArtifact({
+            root,
+            specsFilePath,
+            normalizedSpecPath,
+            specAbsolutePath,
+            bodyContent: parsedFrontmatter?.bodyContent,
+        });
+        if (exactMatch) {
+            return exactMatch;
+        }
+        if (parsedFrontmatter?.source) {
+            return await resolveDerivedSpecTarget({
+                root,
+                specsFilePath,
+                source: parsedFrontmatter.source,
+                bodyContent: parsedFrontmatter.bodyContent,
+            });
+        }
+    }
+    catch {
+        // Provenance is best-effort metadata. Runs should still proceed when
+        // spec-session history cannot be read.
+        return parsedFrontmatter?.invalidProvenance
+            ? {
+                kind: "file",
+                provenance: parsedFrontmatter.invalidProvenance,
+            }
+            : { kind: "file" };
+    }
+    if (parsedFrontmatter?.invalidProvenance) {
+        return {
+            kind: "file",
+            provenance: parsedFrontmatter.invalidProvenance,
+        };
+    }
+    return { kind: "file" };
+}
+async function readExactSpecArtifact(options) {
+    const { root, specsFilePath, normalizedSpecPath, specAbsolutePath, bodyContent, } = options;
+    const [record] = await readSpecRecords({
+        root,
+        specsFilePath,
+        limit: 1,
+        predicate: (entry) => entry.agents.some((agent) => typeof agent.outputPath === "string" &&
+            normalizePathForDisplay(agent.outputPath) === normalizedSpecPath),
+    });
+    if (!record) {
+        return undefined;
+    }
+    const agent = record.agents.find((entry) => typeof entry.outputPath === "string" &&
+        normalizePathForDisplay(entry.outputPath) === normalizedSpecPath);
+    if (!agent) {
+        return {
+            kind: "spec",
+            sessionId: record.sessionId,
+        };
+    }
+    const source = toRecordedSpecSourceDescriptor({
+        sessionId: record.sessionId,
+        agent,
+    });
+    if (!source) {
+        return {
+            kind: "spec",
+            sessionId: record.sessionId,
+        };
+    }
+    const currentBodyContent = typeof bodyContent === "string"
+        ? bodyContent
+        : await readSpecBodyContent(specAbsolutePath);
+    if (typeof currentBodyContent !== "string") {
+        return {
+            kind: "spec",
+            sessionId: record.sessionId,
+        };
+    }
+    const currentContentHash = hashSpecBody(currentBodyContent);
+    return {
+        kind: "spec",
+        sessionId: record.sessionId,
+        provenance: currentContentHash === source.contentHash
+            ? {
+                lineage: "exact",
+                source,
+            }
+            : {
+                lineage: "derived_modified",
+                source,
+                currentContentHash,
+            },
+    };
+}
+async function resolveDerivedSpecTarget(options) {
+    const { root, specsFilePath, source, bodyContent } = options;
+    const currentContentHash = hashSpecBody(bodyContent);
+    const [record] = await readSpecRecords({
+        root,
+        specsFilePath,
+        limit: 1,
+        predicate: (entry) => entry.sessionId === source.sessionId,
+    });
+    if (!record) {
+        return {
+            kind: "spec",
+            sessionId: source.sessionId,
+            provenance: {
+                lineage: "invalid",
+                issueCode: "stale_source",
+                source: toRunSpecSourceHint(source),
+                currentContentHash,
+            },
+        };
+    }
+    const agent = record.agents.find((entry) => entry.agentId === source.agentId);
+    const resolvedSource = agent
+        ? toRecordedSpecSourceDescriptor({
+            sessionId: source.sessionId,
+            agent,
+        })
+        : undefined;
+    if (!agent) {
+        return {
+            kind: "spec",
+            sessionId: source.sessionId,
+            provenance: {
+                lineage: "invalid",
+                issueCode: "stale_source",
+                source: toRunSpecSourceHint(source),
+                currentContentHash,
+            },
+        };
+    }
+    if (!resolvedSource) {
+        return {
+            kind: "spec",
+            sessionId: source.sessionId,
+        };
+    }
+    const sourceContentHash = await readSourceArtifactHash({
+        root,
+        source: resolvedSource,
+    });
+    if (sourceContentHash !== resolvedSource.contentHash) {
+        return {
+            kind: "spec",
+            sessionId: source.sessionId,
+            provenance: {
+                lineage: "invalid",
+                issueCode: "stale_source",
+                source: resolvedSource,
+                currentContentHash,
+            },
+        };
+    }
+    return {
+        kind: "spec",
+        sessionId: source.sessionId,
+        provenance: {
+            lineage: currentContentHash === resolvedSource.contentHash
+                ? "derived"
+                : "derived_modified",
+            source: resolvedSource,
+            currentContentHash,
+        },
+    };
+}
+function parseVoratiqFrontmatter(content) {
+    const frontmatterBlock = extractFrontmatterBlock(content);
+    if (!frontmatterBlock) {
+        return { bodyContent: content };
+    }
+    const hasVoratiqBlock = TOP_LEVEL_VORATIQ_BLOCK_PATTERN.test(frontmatterBlock.headerContent);
+    let document;
+    try {
+        document = load(frontmatterBlock.headerContent, { json: false }) ?? {};
+    }
+    catch {
+        const bodyContent = hasVoratiqBlock
+            ? stripVoratiqFrontmatter(frontmatterBlock)
+            : content;
+        return hasVoratiqBlock
+            ? {
+                bodyContent,
+                invalidProvenance: {
+                    lineage: "invalid",
+                    issueCode: "malformed_frontmatter",
+                    currentContentHash: hashSpecBody(bodyContent),
+                },
+            }
+            : { bodyContent: content };
+    }
+    if (!isObject(document) || !("voratiq" in document)) {
+        return { bodyContent: content };
+    }
+    const bodyContent = stripVoratiqFrontmatter(frontmatterBlock);
+    const parsed = parseVoratiqMetadata(document.voratiq, bodyContent);
+    return {
+        bodyContent,
+        ...parsed,
+    };
+}
+function parseVoratiqMetadata(voratiqBlock, bodyContent) {
+    if (!isObject(voratiqBlock)) {
+        return {
+            invalidProvenance: {
+                lineage: "invalid",
+                issueCode: "malformed_frontmatter",
+                currentContentHash: hashSpecBody(bodyContent),
+            },
+        };
+    }
+    const parsedSource = voratiqFrontmatterSourceSchema.safeParse(voratiqBlock.source);
+    if (!parsedSource.success) {
+        return {
+            invalidProvenance: {
+                lineage: "invalid",
+                issueCode: "malformed_frontmatter",
+                currentContentHash: hashSpecBody(bodyContent),
+            },
+        };
+    }
+    return {
+        source: {
+            sessionId: parsedSource.data.sessionId,
+            agentId: parsedSource.data.agentId,
+        },
+    };
+}
+function extractFrontmatterBlock(content) {
+    const match = FRONTMATTER_PATTERN.exec(content);
+    if (!match) {
+        return undefined;
+    }
+    return {
+        headerContent: match[1] ?? "",
+        bodyContent: content.slice(match[0].length),
+        lineBreak: match[0].includes("\r\n") ? "\r\n" : "\n",
+    };
+}
+async function readSourceArtifactHash(options) {
+    const { root, source } = options;
+    try {
+        const sourceContent = await readFile(resolve(root, source.outputPath), "utf8");
+        return hashSpecBody(parseVoratiqFrontmatter(sourceContent).bodyContent);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readSpecBodyContent(specAbsolutePath) {
+    if (!specAbsolutePath) {
+        return undefined;
+    }
+    try {
+        return parseVoratiqFrontmatter(await readFile(specAbsolutePath, "utf8"))
+            .bodyContent;
+    }
+    catch {
+        return undefined;
+    }
+}
+function stripVoratiqFrontmatter(frontmatterBlock) {
+    const strippedHeader = removeTopLevelYamlBlock(frontmatterBlock.headerContent, "voratiq", frontmatterBlock.lineBreak);
+    if (strippedHeader.trim().length === 0) {
+        return frontmatterBlock.bodyContent;
+    }
+    return ["---", strippedHeader, "---", frontmatterBlock.bodyContent].join(frontmatterBlock.lineBreak);
+}
+function hashSpecBody(content) {
+    return `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
+}
+function toRecordedSpecSourceDescriptor(options) {
+    const { sessionId, agent } = options;
+    if (typeof agent.outputPath !== "string" ||
+        typeof agent.contentHash !== "string") {
+        return undefined;
+    }
+    return {
+        kind: "spec",
+        sessionId,
+        agentId: agent.agentId,
+        outputPath: normalizePathForDisplay(agent.outputPath),
+        contentHash: agent.contentHash,
+    };
+}
+function toRunSpecSourceHint(source) {
+    return {
+        kind: "spec",
+        sessionId: source.sessionId,
+        agentId: source.agentId,
+    };
+}
+function removeTopLevelYamlBlock(headerContent, key, lineBreak) {
+    const lines = headerContent.split(lineBreak);
+    const startIndex = lines.findIndex((line) => new RegExp(`^${key}\\s*:(?:[ \\t]*(?:#.*)?)?$`, "u").test(line));
+    if (startIndex === -1) {
+        return headerContent;
+    }
+    let endIndex = startIndex + 1;
+    while (endIndex < lines.length) {
+        const currentLine = lines[endIndex];
+        if (currentLine === undefined) {
+            break;
+        }
+        if (currentLine.trim().length === 0) {
+            const nextNonEmptyIndex = findNextNonEmptyLineIndex(lines, endIndex + 1);
+            if (nextNonEmptyIndex !== undefined &&
+                /^[ \t]/u.test(lines[nextNonEmptyIndex] ?? "")) {
+                endIndex += 1;
+                continue;
+            }
+            break;
+        }
+        if (!/^[ \t]/u.test(currentLine)) {
+            break;
+        }
+        endIndex += 1;
+    }
+    return [...lines.slice(0, startIndex), ...lines.slice(endIndex)].join(lineBreak);
+}
+function findNextNonEmptyLineIndex(lines, startIndex) {
+    for (let index = startIndex; index < lines.length; index += 1) {
+        if ((lines[index] ?? "").trim().length > 0) {
+            return index;
+        }
+    }
+    return undefined;
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/commands/run/validation.d.ts

@@ -1,13 +1,17 @@
 import type { AgentDefinition } from "../../configs/agents/types.js";
 import type { EnvironmentConfig } from "../../configs/environment/types.js";
+import type { RunSpecTarget } from "../../domain/run/model/types.js";
 export interface ValidationInput {
     readonly root: string;
     readonly specAbsolutePath: string;
+    readonly specDisplayPath?: string;
+    readonly specsFilePath?: string;
     readonly resolvedAgentIds?: readonly string[];
     readonly maxParallel?: number;
 }
 export interface ValidationResult {
     readonly specContent: string;
+    readonly specTarget: RunSpecTarget;
     readonly baseRevisionSha: string;
     readonly agents: readonly AgentDefinition[];
     readonly effectiveMaxParallel: number;