@sanity/ailf 3.4.1 → 3.5.1

package/dist/commands/pipeline.js

@@ -8,12 +8,11 @@
  * @see docs/cli.md for the full flag reference.
  */
 import { Command } from "commander";
-import { LiteracyVariant } from "../pipeline/normalize-mode.js";
 import { addAgenticOptions, addDebugOptions, addSanitySourceOptions, } from "./shared/options.js";
 export function createPipelineCommand() {
     const cmd = new Command("pipeline")
         .description("Run the full evaluation pipeline")
-        .option("-m, --mode <mode>", "Evaluation mode: literacy (default), mcp-server, agent-harness, knowledge-probe, custom. Legacy aliases (baseline, agentic, observed, full) are accepted and normalized to literacy + variant.", LiteracyVariant.FULL)
+        .option("-m, --mode <mode>", "Evaluation mode: literacy (default), mcp-server, agent-harness, knowledge-probe, custom. Legacy aliases (baseline, agentic, observed, full) are accepted and normalized to literacy + variant.", "literacy")
         .option("--variant <variant>", "Literacy variant: full (default — standard + agentic), baseline (standard only), agentic (agentic only), observed. Only applies to --mode literacy.")
         .option("-s, --source <name>", "Documentation source name (from sources.yaml)")
         .option("-n, --dry-run", "Validate configuration only, no execution", false)
@@ -58,6 +57,21 @@ export function createPipelineCommand() {
         .option("--artifacts-dir <path>", "Root directory for local artifact output (D0033; default: .ailf/results/captures/)")
         .option("--artifacts-dry-run", "Run artifact writers in dry-run mode — log intended writes, touch no storage", false)
         .option("--artifacts-exclude <types>", "Comma-separated artifact types to skip (e.g. traces,graderPrompts)")
+        // D0037 caller envelope (W0069) — threads through --remote so the
+        // server-side pipeline attributes provenance to the caller, not the
+        // API gateway runner. All env-var equivalents are honored too;
+        // explicit flags win over env vars.
+        .option("--classification <value>", "Run classification for provenance: official | ad-hoc | experimental | test | external. Overrides AILF_CLASSIFICATION. See D0037.")
+        .option("--owner-team <slug>", "Team slug this run is attributable to. Overrides AILF_OWNER_TEAM.")
+        .option("--owner-individual <slug>", "Individual (GH actor / user ID) this run is attributable to. Overrides AILF_OWNER_INDIVIDUAL.")
+        .option("--purpose <text>", 'Free-text "why I ran this" attached to provenance. Overrides AILF_PURPOSE.')
+        .option("--label <value>", "Free-form searchable label (repeatable). Appends to any AILF_LABELS env value.", (val, prev) => [
+        ...prev,
+        ...val
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean),
+    ], [])
         .action(async (opts) => {
         const { executePipeline } = await import("./pipeline-action.js");
         await executePipeline(opts);

package/dist/commands/remote-pipeline.js

@@ -14,7 +14,7 @@
  * @see docs/design-docs/cli-as-api-client.md — design doc
  */
 import { ZodError } from "zod";
-import { ApiClient, buildRemoteRequest, createProgressDisplay, formatJobError, resolveTasksDir, } from "../adapters/api-client/index.js";
+import { ApiClient, buildRemoteRequest, createProgressDisplay, formatJobError, NoRunnableTasksError, resolveTasksDir, } from "../adapters/api-client/index.js";
 import { writeRemoteResults } from "./remote-results.js";
 // ---------------------------------------------------------------------------
 // Public API
@@ -66,6 +66,10 @@ export async function runRemotePipeline(opts, rootDir) {
             console.error("💡 Fix the issues above in your .ailf/tasks/ YAML files.");
             process.exit(2);
         }
+        if (err instanceof NoRunnableTasksError) {
+            console.error(`❌ ${err.message}`);
+            process.exit(2);
+        }
         throw err;
     }
     console.log(`📦 Found ${taskCount} task(s) in ${tasksDir}`);
@@ -103,6 +107,7 @@ export async function runRemotePipeline(opts, rootDir) {
 function toConfigSlice(opts) {
     return {
         mode: opts.mode,
+        variant: opts.variant,
         debug: opts.debug,
         areas: opts.areaOption
             ?.split(",")
@@ -133,5 +138,12 @@ function toConfigSlice(opts) {
         readinessEnabled: opts.readinessEnabled,
         discoveryReportEnabled: opts.discoveryReportEnabled,
         noRemoteCache: opts.noRemoteCache,
+        // D0037 / W0069 caller envelope overrides — flags override env vars
+        // inside buildCallerEnvelope(), which also merges AILF_* defaults.
+        classificationOption: opts.classificationOption,
+        ownerTeamOption: opts.ownerTeamOption,
+        ownerIndividualOption: opts.ownerIndividualOption,
+        purposeOption: opts.purposeOption,
+        labelOptions: opts.labelOptions,
     };
 }

package/dist/orchestration/steps/finalize-run-step.js

@@ -77,6 +77,7 @@ export class FinalizeRunStep {
         const runContext = buildRunContext({
             areas: maybeSummary?.scores?.map((s) => s.feature) ?? ctx.config.areas ?? [],
             callerGit: ctx.config.callerGit,
+            callerEnvelope: ctx.config.callerEnvelope,
             evalFingerprint: state.evalFingerprint ?? this.options.evalFingerprint,
             logger: ctx.logger,
             mode: ctx.config.mode,

package/dist/orchestration/steps/publish-report-step.js

@@ -225,6 +225,7 @@ function buildProvenanceInput(summary, ctx, options, autoScope) {
         areas,
         autoScope,
         callerGit: ctx.config.callerGit,
+        callerEnvelope: ctx.config.callerEnvelope,
         evalFingerprint,
         mode,
         promptfooUrls: options.promptfooUrls,

package/dist/pipeline/map-request-to-config.js

@@ -72,6 +72,7 @@ export function mapRequestToConfig(request, rootDir) {
         beforeOption: undefined,
         repoTasksPath: undefined,
         callerGit: request.callerGit,
+        callerEnvelope: buildCallerEnvelope(request),
         callback: request.callback,
         jobId: request.jobId,
         remote: false,
@@ -91,6 +92,23 @@ function mapDebug(debug) {
         sample: debug.sample,
     };
 }
+/**
+ * Collect the D0037 caller envelope fields from a PipelineRequest into a
+ * single `callerEnvelope` object. Returns undefined when no envelope
+ * fields were provided, so downstream consumers can short-circuit with
+ * `config.callerEnvelope?.classification` etc.
+ */
+function buildCallerEnvelope(request) {
+    const { classification, owner, executor, purpose, labels } = request;
+    if (classification === undefined &&
+        owner === undefined &&
+        executor === undefined &&
+        purpose === undefined &&
+        labels === undefined) {
+        return undefined;
+    }
+    return { classification, owner, executor, purpose, labels };
+}
 function mapTaskSourceType(taskMode) {
     if (taskMode === "content-lake")
         return taskMode;

package/dist/pipeline/run-context.d.ts

@@ -13,6 +13,7 @@
  * @see docs/decisions/D0032-run-anchored-artifact-store.md (§ Move 5 — Drift Prevention)
  */
 import type { Logger, RunContext } from "../_vendor/ailf-core/index.d.ts";
+import { type RunClassification, type RunExecutor, type RunExecutorSurface, type RunHost, type RunLineage, type RunOwner, type RunTool } from "../_vendor/ailf-shared/index.d.ts";
 import type { ResolvedSourceConfig } from "../sources.js";
 import type { EvalMode } from "./types.js";
 /**
@@ -34,8 +35,35 @@ export interface RunContextInput {
         repo: string;
         sha?: string;
     };
+    /**
+     * Caller-provided D0037 envelope from a `--remote` PipelineRequest.
+     * When set, overrides the server-env detection so the caller's intent
+     * survives the API boundary. Same override pattern as `callerGit`.
+     *
+     * Only caller-identity fields are carried — `executor.email`, `tool`,
+     * and `host` stay server-inferred.
+     *
+     * @see docs/decisions/D0037-run-classification-and-ownership-taxonomy.md
+     */
+    callerEnvelope?: {
+        classification?: RunClassification;
+        owner?: {
+            team: string;
+            individual?: string;
+        };
+        executor?: {
+            type: "user";
+            surface: RunExecutorSurface;
+            name?: string;
+            githubActor?: string;
+        };
+        purpose?: string;
+        labels?: string[];
+    };
     /** Evaluation fingerprint for cross-environment cache lookup */
     evalFingerprint?: string;
+    /** Caller-supplied run lineage (re-runs, comparison partners, parent job). */
+    lineage?: RunLineage;
     /** Logger instance (defaults to ConsoleLogger) */
     logger?: Logger;
     /** Evaluation mode */
@@ -55,3 +83,38 @@ export interface RunContextInput {
  * former directly, the latter transitively through `buildProvenance`.
  */
 export declare function buildRunContext(input: RunContextInput): RunContext;
+/**
+ * Resolve `classification` from `AILF_CLASSIFICATION`, validated against
+ * the closed enum. Defaults to `"ad-hoc"` so unannotated runs never leak
+ * into the canonical `"official"` series.
+ */
+export declare function detectClassification(log: Logger): RunClassification;
+/**
+ * Resolve `owner` from `AILF_OWNER_TEAM` (+ optional
+ * `AILF_OWNER_INDIVIDUAL`). `team` is free-form; default is `"unknown"`.
+ */
+export declare function detectOwner(): RunOwner;
+/**
+ * Detect who/what invoked the run.
+ *
+ * Priority:
+ * 1. GitHub Actions context → `{ type: "system", name: "github-actions", ... }`
+ * 2. CLI context → `{ type: "user", surface: "cli", ... }` with git-config
+ *    or OS username fallback. Email capture gated by
+ *    `AILF_CAPTURE_EMAIL` (default on; set `0` to opt out).
+ *
+ * Every identity field is optional — missing git, containers, or masked
+ * env vars must never block a run.
+ */
+export declare function detectExecutor(): RunExecutor;
+/**
+ * Resolve `tool` — which AILF/Node ran the eval. Captured on every new
+ * run so cross-version trend comparisons can isolate framework changes
+ * from doc changes.
+ */
+export declare function detectTool(log: Logger): RunTool;
+/**
+ * Resolve `host` — platform + arch + CI provider. Hostname is
+ * intentionally excluded (leaks identity without filtering benefit).
+ */
+export declare function detectHost(): RunHost;

package/dist/pipeline/run-context.js

@@ -12,8 +12,13 @@
  *
  * @see docs/decisions/D0032-run-anchored-artifact-store.md (§ Move 5 — Drift Prevention)
  */
+import { execSync } from "node:child_process";
+import { createRequire } from "node:module";
+import * as os from "node:os";
+import { isRunClassification, } from "../_vendor/ailf-shared/index.js";
 import { ConsoleLogger } from "../adapters/loggers/index.js";
 import { tryLoadConfigFile } from "./compiler/config-loader.js";
+const requireFromHere = createRequire(import.meta.url);
 /**
  * Derive `RunContext` from pipeline inputs. The only construction path.
  *
@@ -35,6 +40,21 @@ export function buildRunContext(input) {
         }
         : detectGitMetadata();
     const trigger = detectTrigger();
+    // D0037: caller envelope (from PipelineRequest) takes precedence over
+    // server-env detection — same pattern as `callerGit` for identity
+    // preservation across the --remote boundary.
+    const envelope = input.callerEnvelope;
+    const classification = envelope?.classification ?? detectClassification(log);
+    const owner = envelope?.owner ?? detectOwner();
+    const executor = envelope?.executor ?? detectExecutor();
+    // `tool` and `host` are server-environment facts — they always reflect
+    // where this pipeline is actually running, never what a caller claimed.
+    // Callers cannot override these via the envelope and the wire schema
+    // explicitly doesn't carry them (see pipeline-request.ts).
+    const tool = detectTool(log);
+    const host = detectHost();
+    const labels = envelope?.labels ?? detectLabels();
+    const purpose = envelope?.purpose ?? (process.env.AILF_PURPOSE?.trim() || undefined);
     // Non-literacy modes (agent-harness, mcp-server, etc.) don't use the
     // config/models.ts model matrix — listing those models would be
     // misleading. Only include them for literacy mode where they're the
@@ -44,11 +64,18 @@ export function buildRunContext(input) {
         : [];
     return {
         areas: input.areas,
+        classification,
         evalFingerprint: input.evalFingerprint,
+        executor,
         git,
         graderModel: models.grader.id,
+        host,
+        labels,
+        lineage: input.lineage,
         mode: input.mode,
         models: evaluatedModels,
+        owner,
+        purpose,
         source: {
             baseUrl: input.source.baseUrl,
             dataset: input.source.dataset,
@@ -57,6 +84,7 @@ export function buildRunContext(input) {
             projectId: input.source.projectId,
         },
         taskIds: input.taskIds,
+        tool,
         trigger,
     };
 }
@@ -137,6 +165,144 @@ function detectTrigger() {
     return { type: "manual" };
 }
 // ---------------------------------------------------------------------------
+// Classification, owner, executor, labels, tool, host detection (D0037)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve `classification` from `AILF_CLASSIFICATION`, validated against
+ * the closed enum. Defaults to `"ad-hoc"` so unannotated runs never leak
+ * into the canonical `"official"` series.
+ */
+export function detectClassification(log) {
+    const raw = process.env.AILF_CLASSIFICATION?.trim();
+    if (!raw)
+        return "ad-hoc";
+    if (isRunClassification(raw))
+        return raw;
+    log.warn(`AILF_CLASSIFICATION="${raw}" is not a recognized value; defaulting to "ad-hoc"`);
+    return "ad-hoc";
+}
+/**
+ * Resolve `owner` from `AILF_OWNER_TEAM` (+ optional
+ * `AILF_OWNER_INDIVIDUAL`). `team` is free-form; default is `"unknown"`.
+ */
+export function detectOwner() {
+    const team = process.env.AILF_OWNER_TEAM?.trim() || "unknown";
+    const individual = process.env.AILF_OWNER_INDIVIDUAL?.trim() || undefined;
+    return individual ? { individual, team } : { team };
+}
+/**
+ * Detect who/what invoked the run.
+ *
+ * Priority:
+ * 1. GitHub Actions context → `{ type: "system", name: "github-actions", ... }`
+ * 2. CLI context → `{ type: "user", surface: "cli", ... }` with git-config
+ *    or OS username fallback. Email capture gated by
+ *    `AILF_CAPTURE_EMAIL` (default on; set `0` to opt out).
+ *
+ * Every identity field is optional — missing git, containers, or masked
+ * env vars must never block a run.
+ */
+export function detectExecutor() {
+    if (process.env.GITHUB_ACTIONS === "true") {
+        return {
+            name: "github-actions",
+            runId: process.env.GITHUB_RUN_ID?.trim() || undefined,
+            type: "system",
+            workflow: process.env.GITHUB_WORKFLOW?.trim() || undefined,
+        };
+    }
+    const surface = resolveExecutorSurface();
+    const githubActor = process.env.GITHUB_ACTOR?.trim() || undefined;
+    const name = detectGitConfig("user.name") ?? githubActor ?? osUsername() ?? undefined;
+    const email = shouldCaptureEmail() ? detectGitConfig("user.email") : undefined;
+    const exec = { surface, type: "user" };
+    if (name)
+        exec.name = name;
+    if (email)
+        exec.email = email;
+    if (githubActor)
+        exec.githubActor = githubActor;
+    return exec;
+}
+function resolveExecutorSurface() {
+    const explicit = process.env.AILF_EXECUTOR_SURFACE?.trim();
+    if (explicit === "cli" || explicit === "studio" || explicit === "api") {
+        return explicit;
+    }
+    return "cli";
+}
+function shouldCaptureEmail() {
+    const raw = process.env.AILF_CAPTURE_EMAIL?.trim().toLowerCase();
+    if (raw === "0" || raw === "false" || raw === "no")
+        return false;
+    return true;
+}
+function detectGitConfig(key) {
+    try {
+        const value = execSync(`git config --get ${key}`, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 500,
+        }).trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function osUsername() {
+    try {
+        return os.userInfo().username || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parse `AILF_LABELS` (comma-separated) into a trimmed unique list.
+ * Returns undefined when empty so absent labels stay absent.
+ */
+function detectLabels() {
+    const raw = process.env.AILF_LABELS;
+    if (!raw)
+        return undefined;
+    const labels = raw
+        .split(",")
+        .map((label) => label.trim())
+        .filter(Boolean);
+    if (labels.length === 0)
+        return undefined;
+    return Array.from(new Set(labels));
+}
+/**
+ * Resolve `tool` — which AILF/Node ran the eval. Captured on every new
+ * run so cross-version trend comparisons can isolate framework changes
+ * from doc changes.
+ */
+export function detectTool(log) {
+    const nodeVersion = process.version;
+    let ailfVersion;
+    try {
+        const pkg = requireFromHere("../../package.json");
+        ailfVersion = pkg.version;
+    }
+    catch (err) {
+        log.warn(`Could not read @sanity/ailf package.json for tool.ailfVersion: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { ailfVersion: ailfVersion ?? "unknown", nodeVersion };
+}
+/**
+ * Resolve `host` — platform + arch + CI provider. Hostname is
+ * intentionally excluded (leaks identity without filtering benefit).
+ */
+export function detectHost() {
+    const ci = process.env.GITHUB_ACTIONS === "true" ? "github-actions" : undefined;
+    const host = { arch: os.arch(), platform: os.platform() };
+    if (ci)
+        host.ci = ci;
+    return host;
+}
+// ---------------------------------------------------------------------------
 // Model config loading
 // ---------------------------------------------------------------------------
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/ailf",
-  "version": "3.4.1",
+  "version": "3.5.1",
   "private": false,
   "publishConfig": {
     "access": "public"