@sanity/ailf 0.1.34 → 0.3.0

package/dist/pipeline/mirror-repo-tasks.js

@@ -13,7 +13,9 @@
  * @see docs/exec-plans/tasks-as-content/phase-5-content-lake-mirroring.md
  */
 import { createHash } from "crypto";
-import { isSlugRef, } from "../_vendor/ailf-core/index.js";
+import { readFileSync } from "fs";
+import { isIdRef, isPathRef, isPerspectiveRef, isSlugRef, } from "../_vendor/ailf-core/index.js";
+import { ConsoleLogger } from "../adapters/loggers/index.js";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -29,7 +31,8 @@ import { isSlugRef, } from "../_vendor/ailf-core/index.js";
  * 6. Upsert the ailf.task document with origin block
  */
 export async function mirrorRepoTasks(options) {
-    const { client, tasks, git, dryRun = false } = options;
+    const { client, tasks, git, dryRun = false, logger } = options;
+    const log = logger ?? new ConsoleLogger();
     const result = {
         total: tasks.length,
         upserted: 0,
@@ -54,29 +57,37 @@ export async function mirrorRepoTasks(options) {
     }
     // Ensure all feature areas exist
     const areas = [...new Set(tasks.map((t) => t.featureArea))];
-    const createdAreas = await ensureFeatureAreas(client, areas, dryRun);
+    const createdAreas = await ensureFeatureAreas(client, areas, dryRun, log);
     result.areasCreated = createdAreas;
-    // Fetch existing mirror document content hashes for change detection
+    // Fetch existing mirror document state for change detection + ownership check
     const mirrorIds = tasks.map((t) => mirrorDocId(git.owner, git.name, t.id));
-    const existingHashes = await fetchExistingHashes(client, mirrorIds);
+    const existingDocState = await fetchExistingDocState(client, mirrorIds);
     // Mirror each task
     for (const task of tasks) {
         try {
             const docId = mirrorDocId(git.owner, git.name, task.id);
+            const existing = existingDocState.get(docId);
+            // Skip graduated tasks — ownership was changed to "studio"
+            if (existing?.ownership === "studio") {
+                log.info(`  ℹ️  Skipping "${task.id}" — graduated to Studio ownership`);
+                result.skipped++;
+                continue;
+            }
             const contentHash = computeTaskHash(task);
             // Skip unchanged
-            if (existingHashes.get(docId) === contentHash) {
+            if (existing?.hash === contentHash) {
                 result.skipped++;
                 continue;
             }
             const doc = buildMirrorDocument(task, {
                 contentHash,
                 docId,
+                existingAuthor: existing?.existingAuthor,
                 git,
                 slugToDocId,
             });
             if (dryRun) {
-                console.log(`  [dry-run] Would upsert: ${docId}`);
+                log.info(`  [dry-run] Would upsert: ${docId}`);
                 result.upserted++;
                 continue;
             }
@@ -106,12 +117,15 @@ export async function detectGitContext(repoTasksPath) {
     if (ghRepo) {
         const [owner, name] = ghRepo.split("/");
         const branch = ghHeadRef || ghRef.replace("refs/heads/", "").replace("refs/tags/", "");
+        // Extract author from GitHub Actions environment
+        const author = detectGitHubActionsAuthor();
         return {
             repo: ghRepo,
             owner: owner ?? "unknown",
             name: name ?? "unknown",
             branch: branch || "unknown",
             commitSha: ghSha || "unknown",
+            author,
         };
     }
     // Fallback: try git CLI
@@ -134,12 +148,15 @@ export async function detectGitContext(repoTasksPath) {
             remote.match(/([^/]+)\/([^/.]+?)(?:\.git)?$/);
         const owner = match?.[1] ?? "unknown";
         const name = match?.[2] ?? "unknown";
+        // Extract author from git log
+        const author = detectGitCliAuthor(repoTasksPath, execSync);
         return {
             repo: `${owner}/${name}`,
             owner,
             name,
             branch,
             commitSha,
+            author,
         };
     }
     catch {
@@ -149,10 +166,63 @@ export async function detectGitContext(repoTasksPath) {
             name: "unknown",
             branch: "unknown",
             commitSha: "unknown",
+            author: {},
         };
     }
 }
 // ---------------------------------------------------------------------------
+// Author detection helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract author info from GitHub Actions environment variables and
+ * the webhook event payload (GITHUB_EVENT_PATH).
+ */
+function detectGitHubActionsAuthor() {
+    const ghActor = process.env.GITHUB_ACTOR ?? undefined;
+    const author = { githubUsername: ghActor };
+    // Try to read richer author info from the event payload
+    const eventPath = process.env.GITHUB_EVENT_PATH;
+    if (eventPath) {
+        try {
+            const event = JSON.parse(readFileSync(eventPath, "utf-8"));
+            // Push event: head_commit.author has name + email
+            if (event.head_commit?.author) {
+                author.gitName = event.head_commit.author.name ?? undefined;
+                author.gitEmail = event.head_commit.author.email ?? undefined;
+            }
+            // PR event: pull_request.user.login is the PR author
+            if (event.pull_request?.user?.login) {
+                author.githubUsername = event.pull_request.user.login;
+            }
+        }
+        catch {
+            // Event payload parsing is best-effort — fall through with GITHUB_ACTOR only
+        }
+    }
+    return author;
+}
+/**
+ * Extract author info from git CLI (local fallback when not in GitHub Actions).
+ */
+function detectGitCliAuthor(cwd, execSyncFn) {
+    try {
+        const authorLine = execSyncFn('git log -1 --format="%an|%ae"', {
+            encoding: "utf-8",
+            cwd,
+        })
+            .toString()
+            .trim();
+        const [gitName, gitEmail] = authorLine.split("|");
+        return {
+            gitName: gitName || undefined,
+            gitEmail: gitEmail || undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+// ---------------------------------------------------------------------------
 // Document ID scheme
 // ---------------------------------------------------------------------------
 /**
@@ -219,7 +289,7 @@ async function batchResolveDocSlugs(client, slugs) {
  * Ensure ailf.featureArea documents exist for all referenced areas.
  * Returns the list of newly created area IDs.
  */
-async function ensureFeatureAreas(client, areas, dryRun) {
+async function ensureFeatureAreas(client, areas, dryRun, log) {
     if (areas.length === 0)
         return [];
     // Check which areas already exist
@@ -230,7 +300,7 @@ async function ensureFeatureAreas(client, areas, dryRun) {
         return [];
     if (dryRun) {
         for (const area of missing) {
-            console.log(`  [dry-run] Would create feature area: ${area}`);
+            log.info(`  [dry-run] Would create feature area: ${area}`);
         }
         return missing;
     }
@@ -247,42 +317,82 @@ async function ensureFeatureAreas(client, areas, dryRun) {
     await transaction.commit();
     return missing;
 }
-// ---------------------------------------------------------------------------
-// Fetch existing content hashes
-// ---------------------------------------------------------------------------
 /**
- * Fetch existing mirror documents' content hashes for change detection.
- * The hash is stored in origin.contentHash on the document.
+ * Fetch existing mirror documents' ownership and content hashes.
+ *
+ * The ownership field determines whether the mirror step is allowed to
+ * update the document:
+ * - `"repo"` or absent → safe to update (active mirror)
+ * - `"studio"` → skip (graduated to Studio ownership)
+ *
+ * The hash is stored in origin.contentHash for change detection.
  */
-async function fetchExistingHashes(client, docIds) {
+async function fetchExistingDocState(client, docIds) {
     if (docIds.length === 0)
         return new Map();
-    const query = `*[_id in $ids] { _id, "hash": origin.contentHash }`;
-    const results = await client.fetch(query, {
-        ids: docIds,
-    });
+    const query = `*[_id in $ids] {
+    _id,
+    "hash": origin.contentHash,
+    ownership,
+    "existingAuthor": origin.author
+  }`;
+    const results = await client.fetch(query, { ids: docIds });
     const map = new Map();
     for (const r of results) {
-        if (r.hash)
-            map.set(r._id, r.hash);
+        map.set(r._id, {
+            hash: r.hash ?? undefined,
+            ownership: r.ownership ?? undefined,
+            existingAuthor: r.existingAuthor ?? undefined,
+        });
     }
     return map;
 }
 // ---------------------------------------------------------------------------
 // Build mirror document
 // ---------------------------------------------------------------------------
-function buildMirrorDocument(task, opts) {
-    const { contentHash, docId, git, slugToDocId } = opts;
-    // Build canonical docs with resolved references.
-    // Only slug refs can be resolved to article references today.
-    // Other ref types (path, id, perspective) are stored with reason only.
+/** @internal Exported for testing — not part of the public API. */
+export function buildMirrorDocument(task, opts) {
+    const { contentHash, docId, existingAuthor, git, slugToDocId } = opts;
+    // Build canonical docs with resolved references and correct refType.
+    // Each ref type gets the appropriate resolution fields set on the
+    // mirror document so Studio can display them correctly.
     const canonicalDocs = task.canonicalDocs.map((ref, i) => {
-        const resolvedId = isSlugRef(ref) ? slugToDocId.get(ref.slug) : undefined;
-        return {
-            _key: `cd${i}`,
-            ...(resolvedId ? { doc: { _ref: resolvedId, _type: "reference" } } : {}),
-            reason: ref.reason ?? "",
-        };
+        const base = { _key: `cd${i}`, reason: ref.reason ?? "" };
+        if (isSlugRef(ref)) {
+            const resolvedId = slugToDocId.get(ref.slug);
+            // When a slug resolves to a document, store as "id" ref with
+            // the resolved article reference. When unresolved, store as
+            // "slug" so Studio knows the resolution strategy even if the
+            // article doesn't exist yet.
+            return {
+                ...base,
+                refType: resolvedId ? "id" : "slug",
+                ...(resolvedId
+                    ? { doc: { _ref: resolvedId, _type: "reference" } }
+                    : {}),
+            };
+        }
+        if (isPathRef(ref)) {
+            return { ...base, refType: "path", path: ref.path };
+        }
+        if (isIdRef(ref)) {
+            return {
+                ...base,
+                refType: "id",
+                ...(ref.id
+                    ? { doc: { _ref: ref.id, _type: "reference" }, docId: ref.id }
+                    : {}),
+            };
+        }
+        if (isPerspectiveRef(ref)) {
+            return {
+                ...base,
+                refType: "perspective",
+                perspective: ref.perspective,
+            };
+        }
+        // Unknown ref type — store with reason only
+        return base;
     });
     // Build assertions
     const assertArray = task.assertions.map((a, i) => {
@@ -315,6 +425,8 @@ function buildMirrorDocument(task, opts) {
     return {
         _id: docId,
         _type: "ailf.task",
+        ownership: "repo",
+        status: task.status ?? "active",
         assert: assertArray,
         canonicalDocs,
         description: task.description,
@@ -325,6 +437,7 @@ function buildMirrorDocument(task, opts) {
         },
         id: { _type: "slug", current: task.id },
         origin: {
+            // Existing provenance fields
             branch: git.branch,
             commitSha: git.commitSha,
             contentHash,
@@ -334,6 +447,9 @@ function buildMirrorDocument(task, opts) {
             repoName: git.name,
             repoOwner: git.owner,
             type: "repo",
+            // Authorship: author is write-once (preserve existing), lastEditor always updates
+            author: existingAuthor ?? git.author,
+            lastEditor: git.author,
         },
         taskPrompt: task.taskPrompt,
         ...(task.baseline

package/dist/pipeline/provenance.d.ts

@@ -11,11 +11,14 @@
  * @see docs/design-docs/report-store/domain-model.md
  * @see docs/design-docs/report-store/architecture.md — Provenance collection
  */
+import type { Logger } from "../_vendor/ailf-core/index.d.ts";
 import type { ResolvedSourceConfig } from "../sources.js";
 import type { EvalMode, PromptfooUrlEntry, ReportAutoScope, ReportProvenance } from "./types.js";
 export interface ProvenanceInput {
     /** Feature areas that were evaluated */
     areas: string[];
+    /** Logger instance (defaults to ConsoleLogger) */
+    logger?: Logger;
     /** Release auto-scope metadata (when perspective evaluation was scoped) */
     autoScope?: ReportAutoScope;
     /**

package/dist/pipeline/provenance.js

@@ -14,6 +14,7 @@
 import { readFileSync } from "fs";
 import { resolve } from "path";
 import { load } from "js-yaml";
+import { ConsoleLogger } from "../adapters/loggers/index.js";
 /**
  * Build a ReportProvenance object from pipeline context.
  *
@@ -24,7 +25,20 @@ import { load } from "js-yaml";
  * - Optional metadata (context hash, Promptfoo URL)
  */
 export function buildProvenance(input) {
-    const models = loadModelsConfig(input.rootDir);
+    const log = input.logger ?? new ConsoleLogger();
+    const models = loadModelsConfig(input.rootDir, log);
+    log.debug("Assembling provenance input", {
+        mode: input.mode,
+        sourceName: input.source.name,
+        sourceBaseUrl: input.source.baseUrl,
+        areas: input.areas,
+        taskIds: input.taskIds,
+        hasContextHash: Boolean(input.contextHash),
+        hasEvalFingerprint: Boolean(input.evalFingerprint),
+        hasCallerGit: Boolean(input.callerGit),
+        hasSourceReportId: Boolean(input.sourceReportId),
+        modelCount: models.models.length,
+    });
     // Cross-repo evaluations: prefer explicit caller git metadata over
     // CI env vars (which always reflect the AILF core repo).
     const git = input.callerGit
@@ -39,6 +53,14 @@ export function buildProvenance(input) {
     const lineage = input.sourceReportId
         ? { rerunOf: input.sourceReportId }
         : undefined;
+    const trigger = detectTrigger();
+    log.debug("Provenance computed", {
+        triggerType: trigger.type,
+        gitRepo: git?.repo,
+        gitBranch: git?.branch,
+        evalFingerprint: input.evalFingerprint,
+        hasLineage: Boolean(lineage),
+    });
     return {
         areas: input.areas,
         autoScope: input.autoScope,
@@ -149,13 +171,13 @@ function detectTrigger() {
  * Load config/models.yaml to extract model list and grader info.
  * Falls back to a minimal config if the file can't be read.
  */
-function loadModelsConfig(rootDir) {
+function loadModelsConfig(rootDir, log) {
     try {
         const content = readFileSync(resolve(rootDir, "config", "models.yaml"), "utf-8");
         return load(content);
     }
     catch {
-        console.warn("  ⚠️  Could not read config/models.yaml for provenance");
+        log.warn("Could not read config/models.yaml for provenance");
         return {
             defaults: {},
             grader: { id: "unknown" },

package/dist/pipeline/report-title.d.ts

@@ -0,0 +1,66 @@
+/**
+ * pipeline/report-title.ts
+ *
+ * Pure function that generates descriptive report titles from provenance
+ * metadata. The title is the primary display string shown in dashboards,
+ * Slack digests, and Studio views — it conveys trigger context, evaluated
+ * areas, source/perspective, and document scope at a glance.
+ *
+ * Score is intentionally omitted from the title since it is surfaced
+ * heavily elsewhere in the UI. The `tag` field (on Report) is preserved
+ * as a secondary label; the title is the primary display string.
+ *
+ * Segments are joined with ` · ` (middle dot with spaces).
+ *
+ * @see docs/design-docs/report-store/domain-model.md
+ * @see packages/eval/src/pipeline/provenance.ts — builds the provenance input
+ */
+import type { EvalMode, ReportTrigger } from "./types.js";
+/** Input required to generate a human-readable report title. */
+export interface ReportTitleInput {
+    provenance: {
+        /** Feature areas that were evaluated */
+        areas: string[];
+        /** Evaluation mode */
+        mode: EvalMode;
+        /** Resolved documentation source */
+        source: {
+            name: string;
+            perspective?: string;
+        };
+        /** Sanity document IDs targeted (when scoped to specific documents) */
+        targetDocuments?: string[];
+        /** What triggered the evaluation */
+        trigger: ReportTrigger;
+    };
+    /**
+     * Total number of known feature areas in the system.
+     * Used to determine whether to show "All areas" vs "N areas"
+     * when more than 3 areas are evaluated.
+     */
+    totalAreaCount?: number;
+}
+/**
+ * Generate a descriptive report title from provenance metadata.
+ *
+ * The title is composed of up to four segments separated by ` · `:
+ *
+ * 1. **Trigger context** — what initiated the evaluation (always present)
+ * 2. **Areas** — which feature areas were evaluated (omitted if empty)
+ * 3. **Source context** — non-default source or perspective (omitted if default)
+ * 4. **Target documents** — scoped document IDs (omitted if not scoped)
+ *
+ * @example
+ * ```ts
+ * generateReportTitle({
+ *   provenance: {
+ *     areas: ["GROQ", "Mutations"],
+ *     mode: "baseline",
+ *     source: { name: "production" },
+ *     trigger: { type: "manual" },
+ *   },
+ * })
+ * // → "Manual eval · GROQ, Mutations"
+ * ```
+ */
+export declare function generateReportTitle(input: ReportTitleInput): string;

package/dist/pipeline/report-title.js

@@ -0,0 +1,118 @@
+/**
+ * pipeline/report-title.ts
+ *
+ * Pure function that generates descriptive report titles from provenance
+ * metadata. The title is the primary display string shown in dashboards,
+ * Slack digests, and Studio views — it conveys trigger context, evaluated
+ * areas, source/perspective, and document scope at a glance.
+ *
+ * Score is intentionally omitted from the title since it is surfaced
+ * heavily elsewhere in the UI. The `tag` field (on Report) is preserved
+ * as a secondary label; the title is the primary display string.
+ *
+ * Segments are joined with ` · ` (middle dot with spaces).
+ *
+ * @see docs/design-docs/report-store/domain-model.md
+ * @see packages/eval/src/pipeline/provenance.ts — builds the provenance input
+ */
+// ---------------------------------------------------------------------------
+// Segment builders
+// ---------------------------------------------------------------------------
+const SEPARATOR = " · ";
+/** Segment 1 — human-readable trigger context */
+function triggerSegment(trigger) {
+    switch (trigger.type) {
+        case "scheduled": {
+            const name = trigger.schedule.replace(/-/g, " ");
+            return name.charAt(0).toUpperCase() + name.slice(1);
+        }
+        case "ci":
+            return "CI eval";
+        case "webhook":
+            return "Content change";
+        case "cross-repo": {
+            // Only show the repo name if callerRepo looks like "owner/repo".
+            // Numeric IDs (e.g. GITHUB_REPOSITORY_OWNER_ID fallback) are not useful.
+            const repo = trigger.callerRepo;
+            if (repo.includes("/")) {
+                const shortName = repo.split("/").pop() ?? repo;
+                return `Cross-repo (${shortName})`;
+            }
+            return "Cross-repo";
+        }
+        case "manual":
+            return "Manual eval";
+    }
+}
+/** Segment 2 — areas evaluated (omitted when empty) */
+function areasSegment(areas, totalAreaCount) {
+    if (areas.length === 0)
+        return undefined;
+    if (areas.length <= 3) {
+        return areas.join(", ");
+    }
+    if (totalAreaCount !== undefined && areas.length === totalAreaCount) {
+        return "All areas";
+    }
+    return `${areas.length} areas`;
+}
+/** Segment 3 — source context (omitted when default production, no perspective) */
+function sourceSegment(source) {
+    const parts = [];
+    if (source.perspective) {
+        parts.push(`perspective: ${source.perspective}`);
+    }
+    if (source.name !== "production") {
+        parts.push(source.name);
+    }
+    return parts.length > 0 ? parts.join(", ") : undefined;
+}
+/** Segment 4 — target documents (omitted when not scoped) */
+function targetDocumentsSegment(targetDocuments) {
+    if (!targetDocuments || targetDocuments.length === 0)
+        return undefined;
+    if (targetDocuments.length === 1) {
+        return targetDocuments[0];
+    }
+    return `${targetDocuments.length} documents`;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Generate a descriptive report title from provenance metadata.
+ *
+ * The title is composed of up to four segments separated by ` · `:
+ *
+ * 1. **Trigger context** — what initiated the evaluation (always present)
+ * 2. **Areas** — which feature areas were evaluated (omitted if empty)
+ * 3. **Source context** — non-default source or perspective (omitted if default)
+ * 4. **Target documents** — scoped document IDs (omitted if not scoped)
+ *
+ * @example
+ * ```ts
+ * generateReportTitle({
+ *   provenance: {
+ *     areas: ["GROQ", "Mutations"],
+ *     mode: "baseline",
+ *     source: { name: "production" },
+ *     trigger: { type: "manual" },
+ *   },
+ * })
+ * // → "Manual eval · GROQ, Mutations"
+ * ```
+ */
+export function generateReportTitle(input) {
+    const { provenance, totalAreaCount } = input;
+    const segments = [triggerSegment(provenance.trigger)];
+    const areas = areasSegment(provenance.areas, totalAreaCount);
+    if (areas)
+        segments.push(areas);
+    const source = sourceSegment(provenance.source);
+    if (source)
+        segments.push(source);
+    const docs = targetDocumentsSegment(provenance.targetDocuments);
+    if (docs)
+        segments.push(docs);
+    return segments.join(SEPARATOR);
+}

package/dist/report-store.js

@@ -203,6 +203,7 @@ export class ReportStore {
                 reportId: report.id,
                 summary: report.summary,
                 tag: report.tag ?? null,
+                title: report.title ?? null,
             });
             return report.id;
         }
@@ -255,5 +256,6 @@ function toReport(doc) {
         provenance: doc.provenance,
         summary: doc.summary,
         tag: doc.tag,
+        title: doc.title,
     };
 }

package/dist/sinks/bigquery/index.d.ts

@@ -71,6 +71,7 @@ export interface ReportRow {
     source_name: string;
     source_perspective: null | string;
     tag: null | string;
+    title: null | string;
     total_cost: null | number;
     trigger_caller_repo: null | string;
     trigger_type: string;

package/dist/sinks/bigquery/index.js

@@ -213,6 +213,7 @@ export function flattenReportRow(report) {
         source_name: provenance.source.name,
         source_perspective: provenance.source.perspective ?? null,
         tag: report.tag ?? null,
+        title: report.title ?? null,
         total_cost: summary.overall.cost?.total ?? null,
         trigger_caller_repo: provenance.trigger.type === "cross-repo"
             ? provenance.trigger.callerRepo

package/dist/sources.d.ts

@@ -12,6 +12,7 @@
  * Environment variables in config/sources.yaml are resolved via ${{ VAR | default }}
  * interpolation at load time.
  */
+import type { Logger } from "./_vendor/ailf-core/index.d.ts";
 /**
  * @deprecated Use {@link ResolvedSourceConfig} instead.
  * Kept as a type alias for backward compatibility during the transition.
@@ -89,7 +90,7 @@ export interface SourceOverrides {
  * @param name - Source name from config/sources.yaml. If omitted, uses DOC_SOURCE
  *               env var or the first source defined in config/sources.yaml.
  */
-export declare function loadSource(name?: string, overrides?: SourceOverrides): ResolvedSourceConfig;
+export declare function loadSource(name?: string, overrides?: SourceOverrides, logger?: Logger): ResolvedSourceConfig;
 /**
  * Match a hostname against an origin pattern that may contain `*` wildcards.
  *