@sanity/ailf 3.4.0 → 3.5.0

package/dist/_vendor/ailf-shared/run-classification.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Run classification, ownership, executor, and environment metadata.
+ *
+ * These fields extend `RunContext` to capture run *intent*, *attribution*,
+ * and *reproducibility* — orthogonal to the *mechanism* captured by
+ * `RunTrigger`. A scheduled run can be experimental; a manual run can be
+ * official; a PR-triggered run is executed by GH Actions but attributable
+ * to the PR author.
+ *
+ * @see docs/decisions/D0037-run-classification-and-ownership-taxonomy.md
+ * @see docs/design-docs/run-classification-and-ownership.md
+ */
+/**
+ * How a run should be treated for reporting and trend tracking.
+ *
+ * Orthogonal to `RunTrigger` (mechanism). Defaults to `"ad-hoc"` when
+ * unannotated so pre-taxonomy runs never leak into the canonical series.
+ */
+export type RunClassification = "official" | "ad-hoc" | "experimental" | "test" | "external";
+export declare const RUN_CLASSIFICATIONS: readonly RunClassification[];
+export declare function isRunClassification(value: unknown): value is RunClassification;
+/**
+ * Attribution — which team and (optionally) individual the run *belongs to*.
+ *
+ * `team` is a free-form slug, not a closed enum: external teams name
+ * themselves and internal names drift. A soft-normalization layer under
+ * `config/owners.ts` maps aliases to canonical slugs (warn-only).
+ */
+export interface RunOwner {
+    team: string;
+    individual?: string;
+}
+/**
+ * Who or what actually invoked the run.
+ *
+ * Separate from `RunOwner` because they diverge for automated surfaces:
+ * a PR gate is *executed by* GH Actions but *attributable to* the PR
+ * author. Both variants expose a `name` field so consumers can format
+ * them with one template.
+ *
+ * Every detectable identity field is optional — a misconfigured shell,
+ * a container without `git`, or a CI provider that doesn't expose actor
+ * metadata can all still produce a valid run with thin provenance.
+ */
+export type RunExecutor = RunExecutorUser | RunExecutorSystem;
+export interface RunExecutorUser {
+    type: "user";
+    /** Detected from `git config user.name`, `os.userInfo().username`, or GH actor. */
+    name?: string;
+    /** From `git config user.email`. Subject to the `AILF_CAPTURE_EMAIL` opt-out. */
+    email?: string;
+    /** Where the invocation originated. Always knowable. */
+    surface: RunExecutorSurface;
+    /** GH actor when the user invoked via a GH surface (PR, manual dispatch). */
+    githubActor?: string;
+}
+export interface RunExecutorSystem {
+    type: "system";
+    /** e.g. `"github-actions"`, `"vercel-cron"`, `"sanity-webhook"`. */
+    name: string;
+    workflow?: string;
+    runId?: string;
+}
+export type RunExecutorSurface = "cli" | "studio" | "api";
+export declare const RUN_EXECUTOR_SURFACES: readonly RunExecutorSurface[];
+/**
+ * Links to related runs. Fills the gap where the Studio report schema
+ * already carried these fields but `RunContext` did not.
+ */
+export interface RunLineage {
+    /** Prior `RunId` this run re-executes. */
+    rerunOf?: string;
+    /** Sibling `RunId` this run is intentionally compared against. */
+    comparedAgainst?: string;
+    /** API-gateway job ID that dispatched this run. */
+    parentJobId?: string;
+}
+/**
+ * Reproducibility metadata — which AILF/Node ran the eval.
+ *
+ * Required on every new run so cross-version trend comparisons can
+ * isolate framework changes from doc changes.
+ */
+export interface RunTool {
+    ailfVersion: string;
+    nodeVersion: string;
+}
+/**
+ * Platform + CI-provider metadata for debugging flakes. Hostname is
+ * intentionally excluded — it leaks machine/user identity without
+ * filtering benefit.
+ */
+export interface RunHost {
+    /** `os.platform()` — `"darwin"` | `"linux"` | `"win32"`. */
+    platform: string;
+    /** `os.arch()` — `"x64"` | `"arm64"`. */
+    arch: string;
+    /** CI provider when running under one, e.g. `"github-actions"`. */
+    ci?: string;
+}

package/dist/_vendor/ailf-shared/run-classification.js

@@ -0,0 +1,28 @@
+/**
+ * Run classification, ownership, executor, and environment metadata.
+ *
+ * These fields extend `RunContext` to capture run *intent*, *attribution*,
+ * and *reproducibility* — orthogonal to the *mechanism* captured by
+ * `RunTrigger`. A scheduled run can be experimental; a manual run can be
+ * official; a PR-triggered run is executed by GH Actions but attributable
+ * to the PR author.
+ *
+ * @see docs/decisions/D0037-run-classification-and-ownership-taxonomy.md
+ * @see docs/design-docs/run-classification-and-ownership.md
+ */
+export const RUN_CLASSIFICATIONS = [
+    "official",
+    "ad-hoc",
+    "experimental",
+    "test",
+    "external",
+];
+export function isRunClassification(value) {
+    return (typeof value === "string" &&
+        RUN_CLASSIFICATIONS.includes(value));
+}
+export const RUN_EXECUTOR_SURFACES = [
+    "cli",
+    "studio",
+    "api",
+];

package/dist/_vendor/ailf-shared/run-context.d.ts

@@ -15,15 +15,26 @@
  * @see docs/design-docs/run-artifact-store.md (§ Drift Prevention)
  */
 import type { EvalMode } from "./eval-modes.js";
+import type { RunClassification, RunExecutor, RunHost, RunLineage, RunOwner, RunTool } from "./run-classification.js";
 import type { RunTrigger } from "./run-trigger.js";
 export interface RunContext {
     /** Which feature areas were evaluated */
     areas: string[];
+    /**
+     * How this run should be treated for reporting and trend tracking.
+     * Orthogonal to `trigger` (mechanism). Defaults to `"ad-hoc"` when
+     * unannotated — only the scheduled workflow mints `"official"`.
+     *
+     * @see docs/decisions/D0037-run-classification-and-ownership-taxonomy.md
+     */
+    classification: RunClassification;
     /**
      * Evaluation fingerprint — SHA-256 of all inputs that affect eval output.
      * Used for cross-environment cache lookup (CI → Content Lake).
      */
     evalFingerprint?: string;
+    /** Who/what actually invoked the run. May or may not match `owner`. */
+    executor: RunExecutor;
     /** Git metadata (when run from CI) */
     git?: {
         branch: string;
@@ -33,6 +44,12 @@ export interface RunContext {
     };
     /** Grader model used for scoring */
     graderModel: string;
+    /** Platform/CI metadata for debugging flakes. */
+    host?: RunHost;
+    /** Free-form searchable tags — release IDs, regression hunts, experiments. */
+    labels?: string[];
+    /** Links to related runs (re-runs, comparison partners, API parent job). */
+    lineage?: RunLineage;
     /** Evaluation mode */
     mode: EvalMode;
     /** Models under evaluation */
@@ -40,6 +57,10 @@ export interface RunContext {
         id: string;
         label: string;
     }[];
+    /** Which team (and optionally individual) this run is attributable to. */
+    owner: RunOwner;
+    /** Human-authored "why I ran this" — useful for Content Lake archaeology. */
+    purpose?: string;
     /** Documentation source configuration */
     source: {
         baseUrl: string;
@@ -50,6 +71,8 @@ export interface RunContext {
     };
     /** Specific task IDs evaluated when scoped to a subset */
     taskIds?: string[];
+    /** Which AILF/Node ran the eval — for cross-version trend compatibility. */
+    tool?: RunTool;
     /** What initiated this run */
     trigger: RunTrigger;
 }

package/dist/adapters/api-client/build-request.d.ts

@@ -51,6 +51,18 @@ export interface RemoteConfigSlice {
     readinessEnabled?: boolean;
     discoveryReportEnabled?: boolean;
     noRemoteCache?: boolean;
+    /**
+     * D0037 / W0069 — CLI-flag overrides for the caller envelope. These
+     * take precedence over the equivalent env vars when set. When both a
+     * flag and its env var are unset the field is omitted from the
+     * request (server applies its own defaults).
+     */
+    classificationOption?: string;
+    ownerTeamOption?: string;
+    ownerIndividualOption?: string;
+    purposeOption?: string;
+    /** Repeatable --label values; appended to AILF_LABELS env values. */
+    labelOptions?: string[];
 }
 /**
  * Build a PipelineRequest from local tasks and config.
@@ -75,3 +87,22 @@ export declare function buildRemoteRequest(options: BuildRequestOptions): Promis
  * Returns the resolved path or throws if not found.
  */
 export declare function resolveTasksDir(rootDir: string, explicitPath?: string): string;
+/**
+ * Build the D0037 caller envelope payload from CLI flags + env vars.
+ *
+ * Precedence, highest first:
+ *   1. Explicit CLI flag (--classification, --owner-team, --purpose, …)
+ *   2. Env var (AILF_CLASSIFICATION, AILF_OWNER_TEAM, AILF_PURPOSE, …)
+ *   3. Omit — server applies its own defaults (ad-hoc / unknown).
+ *
+ * Labels are additive: --label values concatenate with AILF_LABELS.
+ *
+ * `executor` is always set on remote submissions because we know the
+ * invocation is a user-driven CLI call. Surface defaults to `"cli"`
+ * unless AILF_EXECUTOR_SURFACE explicitly overrides; name falls back to
+ * GITHUB_ACTOR when available.
+ *
+ * Returns partial `PipelineRequest` fields only. Omits any key whose
+ * source (flag + env) was unset.
+ */
+export declare function buildCallerEnvelope(config: RemoteConfigSlice): Partial<PipelineRequest>;

package/dist/adapters/api-client/build-request.js

@@ -15,7 +15,7 @@
 import { existsSync } from "fs";
 import { resolve } from "path";
 import { PipelineRequestSchema, } from "../../_vendor/ailf-core/index.js";
-import { LEGACY_EVAL_MODE_ALIASES } from "../../_vendor/ailf-shared/index.js";
+import { LEGACY_EVAL_MODE_ALIASES, isRunClassification, } from "../../_vendor/ailf-shared/index.js";
 import { LiteracyVariant } from "../../pipeline/normalize-mode.js";
 import { RepoTaskSource } from "../task-sources/repo-task-source.js";
 const LEGACY_LITERACY_VARIANT_SET = new Set(LEGACY_EVAL_MODE_ALIASES);
@@ -127,6 +127,10 @@ export async function buildRemoteRequest(options) {
     const callerGit = detectCallerGit();
     if (callerGit)
         raw.callerGit = callerGit;
+    // D0037 caller envelope — merge CLI flags + env vars and attach each
+    // populated field. Flags override env. Skipped fields are omitted so
+    // the server applies its own defaults.
+    Object.assign(raw, buildCallerEnvelope(config));
     // 4. Validate the assembled request
     const parsed = PipelineRequestSchema.parse(raw);
     return { request: parsed, taskCount: tasks.length };
@@ -210,6 +214,83 @@ function buildFilterOptions(config) {
         return undefined;
     return { areas, taskIds, tags };
 }
+/**
+ * Build the D0037 caller envelope payload from CLI flags + env vars.
+ *
+ * Precedence, highest first:
+ *   1. Explicit CLI flag (--classification, --owner-team, --purpose, …)
+ *   2. Env var (AILF_CLASSIFICATION, AILF_OWNER_TEAM, AILF_PURPOSE, …)
+ *   3. Omit — server applies its own defaults (ad-hoc / unknown).
+ *
+ * Labels are additive: --label values concatenate with AILF_LABELS.
+ *
+ * `executor` is always set on remote submissions because we know the
+ * invocation is a user-driven CLI call. Surface defaults to `"cli"`
+ * unless AILF_EXECUTOR_SURFACE explicitly overrides; name falls back to
+ * GITHUB_ACTOR when available.
+ *
+ * Returns partial `PipelineRequest` fields only. Omits any key whose
+ * source (flag + env) was unset.
+ */
+export function buildCallerEnvelope(config) {
+    const out = {};
+    // Classification: flag > env. Validated against the closed enum.
+    const rawClassification = config.classificationOption ??
+        process.env.AILF_CLASSIFICATION?.trim() ??
+        undefined;
+    if (rawClassification) {
+        if (isRunClassification(rawClassification)) {
+            out.classification = rawClassification;
+        }
+        else {
+            // Surface the invalid value so downstream Zod validation gives a
+            // clear error message pointing at the flag, not the inner enum.
+            out.classification =
+                rawClassification;
+        }
+    }
+    // Owner: flag > env. Team required, individual optional.
+    const team = config.ownerTeamOption ?? process.env.AILF_OWNER_TEAM?.trim() ?? undefined;
+    const individual = config.ownerIndividualOption ??
+        process.env.AILF_OWNER_INDIVIDUAL?.trim() ??
+        process.env.GITHUB_ACTOR?.trim() ??
+        undefined;
+    if (team) {
+        out.owner = individual ? { team, individual } : { team };
+    }
+    // Purpose: flag > env.
+    const purpose = config.purposeOption ?? process.env.AILF_PURPOSE?.trim() ?? undefined;
+    if (purpose)
+        out.purpose = purpose;
+    // Labels: flag AND env are additive (dedup + trim).
+    const flagLabels = config.labelOptions ?? [];
+    const envLabels = (process.env.AILF_LABELS ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const mergedLabels = Array.from(new Set([...envLabels, ...flagLabels]));
+    if (mergedLabels.length > 0)
+        out.labels = mergedLabels;
+    // Executor: always set on remote submissions — we know this is a CLI
+    // user. Only omit when absolutely nothing identifying is available.
+    const surfaceEnv = process.env.AILF_EXECUTOR_SURFACE?.trim();
+    const surface = surfaceEnv === "studio" || surfaceEnv === "api" ? surfaceEnv : "cli";
+    const githubActor = process.env.GITHUB_ACTOR?.trim() || undefined;
+    const nameFromIndividual = config.ownerIndividualOption ??
+        process.env.AILF_OWNER_INDIVIDUAL?.trim() ??
+        undefined;
+    const executorName = githubActor ?? nameFromIndividual;
+    const executor = {
+        type: "user",
+        surface,
+    };
+    if (executorName)
+        executor.name = executorName;
+    if (githubActor)
+        executor.githubActor = githubActor;
+    out.executor = executor;
+    return out;
+}
 /**
  * Auto-detect caller git metadata from GitHub Actions environment variables.
  *

package/dist/adapters/api-client/index.d.ts

@@ -5,7 +5,7 @@
  *   import { ApiClient, buildRemoteRequest, resolveTasksDir } from "./adapters/api-client/index.js"
  */
 export { ApiClient } from "./api-client.js";
-export { buildRemoteRequest, resolveTasksDir, type BuildRequestOptions, type RemoteConfigSlice, } from "./build-request.js";
+export { buildCallerEnvelope, buildRemoteRequest, resolveTasksDir, type BuildRequestOptions, type RemoteConfigSlice, } from "./build-request.js";
 export { ApiAuthError, ApiConnectionError, ApiError, ApiTimeoutError, } from "./errors.js";
 export { formatJobError } from "./format-error.js";
 export { createProgressDisplay } from "./progress.js";

package/dist/adapters/api-client/index.js

@@ -5,7 +5,7 @@
  *   import { ApiClient, buildRemoteRequest, resolveTasksDir } from "./adapters/api-client/index.js"
  */
 export { ApiClient } from "./api-client.js";
-export { buildRemoteRequest, resolveTasksDir, } from "./build-request.js";
+export { buildCallerEnvelope, buildRemoteRequest, resolveTasksDir, } from "./build-request.js";
 export { ApiAuthError, ApiConnectionError, ApiError, ApiTimeoutError, } from "./errors.js";
 export { formatJobError } from "./format-error.js";
 export { createProgressDisplay } from "./progress.js";

package/dist/adapters/task-sources/repo-validation.js

@@ -81,9 +81,11 @@ export function validateCanonicalTasks(tasks) {
                 }
             }
         }
-        // Check task has at least one llm-rubric assertion (recommended but not required)
+        // Check task has at least one llm-rubric assertion (recommended but not required).
+        // agent-harness tasks grade side-effects (file-exists, command-succeeds, etc.),
+        // not text output, so an llm-rubric is not expected.
         const hasLlmRubric = assertions.some((a) => a.type === "llm-rubric");
-        if (!hasLlmRubric) {
+        if (!hasLlmRubric && task.mode !== "agent-harness") {
             warnings.push({
                 taskId: task.id,
                 field: "assertions",

package/dist/commands/explain-handler.js

@@ -727,6 +727,11 @@ async function buildPipelineExplainPlan(actionCommand, rootDir) {
         artifactsDir: raw.artifactsDir,
         artifactsDryRun: raw.artifactsDryRun ?? false,
         artifactsExclude: raw.artifactsExclude,
+        classification: raw.classification,
+        ownerTeam: raw.ownerTeam,
+        ownerIndividual: raw.ownerIndividual,
+        purpose: raw.purpose,
+        label: raw.label ?? [],
     };
     const resolved = computeResolvedOptions(withDefaults);
     const planOpts = {

package/dist/commands/init.js

@@ -258,6 +258,11 @@ async function runInit(opts) {
     console.log(`  1. Edit the example tasks in ${rel(targetDir, tasksDir)}/ — update`);
     console.log("     slugs and prompts for your documentation");
     console.log(`  2. Validate locally: npx @sanity/ailf@latest validate-tasks .ailf/tasks/`);
+    console.log();
+    console.log('     Note: tasks with status: "draft" are skipped on normal runs.');
+    console.log("     To run one anyway, target it explicitly with --task <id>, e.g.:");
+    console.log("       npx @sanity/ailf@latest pipeline --task example-agent-add-schema");
+    console.log();
     console.log("  3. Add a GitHub Actions secret");
     console.log("     (Settings → Secrets and variables → Actions):");
     console.log("     • AILF_API_KEY — your API key");

package/dist/commands/pipeline-action.d.ts

@@ -68,6 +68,12 @@ export interface ResolvedOptions {
     artifactsDir?: string;
     artifactsDryRun: boolean;
     artifactsExclude?: readonly string[];
+    /** D0037 / W0069 caller envelope — surfaces only on --remote today. */
+    classificationOption?: string;
+    ownerTeamOption?: string;
+    ownerIndividualOption?: string;
+    purposeOption?: string;
+    labelOptions: string[];
 }
 /**
  * Pure option resolution — computes ResolvedOptions from CLI flags without

package/dist/commands/pipeline-action.js

@@ -269,6 +269,11 @@ export function computeResolvedOptions(opts) {
         artifactsDir: resolveArtifactsDir(opts),
         artifactsDryRun: opts.artifactsDryRun,
         artifactsExclude: parseArtifactsExcludeList(opts.artifactsExclude),
+        classificationOption: opts.classification?.trim() || undefined,
+        ownerTeamOption: opts.ownerTeam?.trim() || undefined,
+        ownerIndividualOption: opts.ownerIndividual?.trim() || undefined,
+        purposeOption: opts.purpose?.trim() || undefined,
+        labelOptions: opts.label ?? [],
     };
 }
 /**

package/dist/commands/pipeline.d.ts

@@ -68,5 +68,10 @@ export interface PipelineCliOptions {
     artifactsDir?: string;
     artifactsDryRun: boolean;
     artifactsExclude?: string;
+    classification?: string;
+    ownerTeam?: string;
+    ownerIndividual?: string;
+    purpose?: string;
+    label: string[];
 }
 export declare function createPipelineCommand(): Command;

package/dist/commands/pipeline.js

@@ -58,6 +58,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

@@ -133,5 +133,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;