@sanity/ailf 6.1.2 → 7.0.1

package/dist/_vendor/ailf-shared/help-content.js

@@ -0,0 +1,10 @@
+/**
+ * Re-export of the build-generated help-topic table.
+ *
+ * The underlying file `src/generated/help-content.ts` is emitted by
+ * `scripts/extract-help.ts` and is gitignored. Run `pnpm extract-help`
+ * (invoked automatically by this package's `prebuild`) to (re)generate it.
+ *
+ * @see scripts/extract-help.ts
+ */
+export { HELP_TOPICS } from "./generated/help-content.js";

package/dist/_vendor/ailf-shared/help-topics.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Help topic type — extracted from `:::help` remark directives in
+ * `docs/**\/*.md` by `scripts/extract-help.ts`. Consumed by both the
+ * Studio plugin and the App SDK dashboard.
+ *
+ * The extraction script emits `src/generated/help-content.ts` (gitignored)
+ * within this package. Consumers import `HELP_TOPICS` from the package
+ * barrel rather than reaching into the generated path directly.
+ *
+ * @see scripts/extract-help.ts
+ * @see docs/design-docs/contextual-help-sidebar.md
+ */
+export interface HelpTopic {
+    /** URL-safe identifier — matches the #id in the :::help directive */
+    id: string;
+    /** Display title shown in the drawer header */
+    title: string;
+    /** Markdown body content (rendered in the drawer) */
+    body: string;
+    /** Source file path (for debugging / "Edit this page" links) */
+    source: string;
+    /** Related topic IDs — rendered as "See also" links */
+    related?: string[];
+    /** Tags for search/filtering */
+    tags?: string[];
+}

package/dist/_vendor/ailf-shared/help-topics.js

@@ -0,0 +1 @@
+export {};

package/dist/_vendor/ailf-shared/index.d.ts

@@ -21,6 +21,10 @@ export { computeCanaryDrift, type CanaryDriftReport, type CanaryReportSlim, type
 export { type DocumentRef } from "./document-ref.js";
 export { makeEditorialReference, type EditorialReference, type MakeEditorialReferenceArgs, } from "./editorial-reference.js";
 export { FEATURE_FLAGS, type FeatureFlag, type FeatureFlagKey, } from "./feature-flags.js";
+export { DEFAULT_GCS_ARTIFACT_BUCKET } from "./gcs-defaults.js";
+export { GLOSSARY, type GlossaryEntry, type GlossarySlug } from "./glossary.js";
+export { HELP_TOPICS } from "./help-content.js";
+export { type HelpTopic } from "./help-topics.js";
 export { GRADE_BOUNDARIES, scoreGrade, type ScoreGrade, } from "./score-grades.js";
 export { NOISE_THRESHOLD } from "./noise-threshold.js";
 export { CANONICAL_EVAL_MODES, LEGACY_EVAL_MODE_ALIASES, LITERACY_VARIANTS, RAW_EVAL_MODES, type EvalMode, type LiteracyVariant, type RawEvalMode, } from "./eval-modes.js";

package/dist/_vendor/ailf-shared/index.js

@@ -20,6 +20,9 @@
 export { computeCanaryDrift, } from "./canary-drift.js";
 export { makeEditorialReference, } from "./editorial-reference.js";
 export { FEATURE_FLAGS, } from "./feature-flags.js";
+export { DEFAULT_GCS_ARTIFACT_BUCKET } from "./gcs-defaults.js";
+export { GLOSSARY } from "./glossary.js";
+export { HELP_TOPICS } from "./help-content.js";
 export { GRADE_BOUNDARIES, scoreGrade, } from "./score-grades.js";
 export { NOISE_THRESHOLD } from "./noise-threshold.js";
 export { CANONICAL_EVAL_MODES, LEGACY_EVAL_MODE_ALIASES, LITERACY_VARIANTS, RAW_EVAL_MODES, } from "./eval-modes.js";

package/dist/composition-root.js

@@ -18,6 +18,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { ARTIFACT_EXPORT_PHASE_ID, DIAGNOSIS_CARD_GENERATORS, InMemoryPluginRegistry, NoOpArtifactWriter, NoOpProgressReporter, createDiagnosisRunner, createLLMClient, generateRunId, isArtifactType, modelId, } from "./_vendor/ailf-core/index.js";
+import { DEFAULT_GCS_ARTIFACT_BUCKET } from "./_vendor/ailf-shared/index.js";
 import { JudgmentAttributionSchema } from "./adapters/attribution/per-entry-attribution-writer.js";
 import { AccumulatingArtifactWriter } from "./artifact-capture/accumulating-artifact-writer.js";
 import { ApiGatewayArtifactWriter } from "./artifact-capture/api-gateway-artifact-writer.js";
@@ -162,12 +163,13 @@ function createProgressReporter() {
     });
 }
 /**
- * Shared GCS bucket for report artifacts. Matches the gateway default at
- * packages/api/src/routes/artifacts.ts — both sides assume ailf-artifacts
- * unless explicitly overridden. The gateway's signing credentials are scoped
- * to this bucket, so alternate names require reconfiguring the gateway.
+ * Shared GCS bucket for report artifacts. Canonical default lives in
+ * `@sanity/ailf-shared` so the gateway (`packages/api/src/routes/runs.ts`)
+ * and the dashboard read the same value. The gateway's signing credentials
+ * are scoped to this bucket, so alternate names require reconfiguring the
+ * gateway in addition to setting `AILF_GCS_ARTIFACT_BUCKET`.
  */
-const DEFAULT_ARTIFACT_BUCKET = "ailf-artifacts";
+const DEFAULT_ARTIFACT_BUCKET = DEFAULT_GCS_ARTIFACT_BUCKET;
 /**
  * D0033 M4 default root for local artifacts when `--artifacts-dir` is unset.
  * Mirrors the pre-W0050 capture root so existing dev tooling (Studio

package/dist/pipeline/cache-hit-restore.d.ts

@@ -10,12 +10,24 @@
  */
 import type { ArtifactManifest, RunId } from "../_vendor/ailf-core/index.d.ts";
 /**
- * Copy an artifact manifest verbatim and stamp `sourceRunId` on every ref.
+ * Copy an artifact manifest verbatim and stamp `sourceRunId` on every ref
+ * that doesn't already carry one.
  *
  * The ref's `path`, `bucket`, `entries`, `bytes`, `preview`, etc. travel
- * unchanged — they already point at the source run's storage. Only
- * `sourceRunId` is added so retention/GC and observability tooling can
- * follow the cross-run dependency.
+ * unchanged — they already point at the source run's storage. `sourceRunId`
+ * is added so retention/GC and observability tooling can follow the
+ * cross-run dependency.
+ *
+ * **Transitive lineage.** When a cached report's refs already carry a
+ * `sourceRunId` (because that report was itself a cache hit), we preserve it.
+ * `opts.sourceRunId` is only the *immediate* cache parent; if the cached
+ * report's refs already point at the ultimate source run, blindly overwriting
+ * would drop the lineage one hop per cache propagation and 404 readers that
+ * trust `sourceRunId` for path reconstruction.
+ *
+ * Invariant maintained across any number of cache hops: every ref's
+ * `sourceRunId` equals the runId encoded in its `path` (= where the bytes
+ * physically live).
  *
  * Pure function; safe to call without side effects.
  */

package/dist/pipeline/cache-hit-restore.js

@@ -9,12 +9,24 @@
  * @see docs/design-docs/cache-hit-artifact-restoration.md
  */
 /**
- * Copy an artifact manifest verbatim and stamp `sourceRunId` on every ref.
+ * Copy an artifact manifest verbatim and stamp `sourceRunId` on every ref
+ * that doesn't already carry one.
  *
  * The ref's `path`, `bucket`, `entries`, `bytes`, `preview`, etc. travel
- * unchanged — they already point at the source run's storage. Only
- * `sourceRunId` is added so retention/GC and observability tooling can
- * follow the cross-run dependency.
+ * unchanged — they already point at the source run's storage. `sourceRunId`
+ * is added so retention/GC and observability tooling can follow the
+ * cross-run dependency.
+ *
+ * **Transitive lineage.** When a cached report's refs already carry a
+ * `sourceRunId` (because that report was itself a cache hit), we preserve it.
+ * `opts.sourceRunId` is only the *immediate* cache parent; if the cached
+ * report's refs already point at the ultimate source run, blindly overwriting
+ * would drop the lineage one hop per cache propagation and 404 readers that
+ * trust `sourceRunId` for path reconstruction.
+ *
+ * Invariant maintained across any number of cache hops: every ref's
+ * `sourceRunId` equals the runId encoded in its `path` (= where the bytes
+ * physically live).
  *
  * Pure function; safe to call without side effects.
  */
@@ -23,9 +35,10 @@ export function remapToCacheHitRefs(source, opts) {
     for (const [type, ref] of Object.entries(source)) {
         if (!ref)
             continue;
+        const typed = ref;
         out[type] = {
-            ...ref,
-            sourceRunId: opts.sourceRunId,
+            ...typed,
+            sourceRunId: typed.sourceRunId ?? opts.sourceRunId,
         };
     }
     return out;

package/dist/webhook/eval-request-handler.d.ts

@@ -10,21 +10,25 @@
  * Designed to run in any HTTP environment: Cloudflare Workers, Vercel
  * functions, Express, Hono, etc.
  *
- * Supports two scoping modes:
- * - **Release-scoped** — requires `perspective` field
- * - **Task-scoped** — requires `tasks` array (optionally with `areas`)
- *
- * At least one of `perspective` or `tasks` must be present.
+ * The eval-request document carries a canonical `PipelineRequest` JSON
+ * blob in its `pipelineRequest` field (see W0239). The handler parses it
+ * via `PipelineRequestSchema` from `@sanity/ailf-core` and forwards it
+ * to the dispatcher as-is. Scoping (release-scoped via `perspective`,
+ * task-scoped via `tasks`) is asserted on the parsed `PipelineRequest`
+ * — at least one must be present.
  *
  * Flow:
  * 1. Receive eval request payload (from Sanity webhook projection)
- * 2. Validate: must be `ailf.evalRequest` type, `pending` status,
- *    with either `perspective` or `tasks`
- * 3. Dispatch evaluation to GitHub Actions via `repository_dispatch`
- *    with `external-eval` event type and scoped client payload
- * 4. On success: PATCH the eval request document → `status: "dispatched"`
- * 5. On failure: PATCH the eval request document → `status: "failed"` + error
- * 6. Return a structured result
+ * 2. Validate envelope: must be `ailf.evalRequest` type, `pending` status,
+ *    `pipelineRequest` present
+ * 3. Parse + Zod-validate `pipelineRequest` against `PipelineRequestSchema`
+ * 4. Assert scoping: parsed request must have `perspective` or `tasks`
+ * 5. Dispatch evaluation to GitHub Actions via `repository_dispatch`
+ *    with `external-eval` event type — the parsed `PipelineRequest`
+ *    rides as `client_payload.request` unchanged
+ * 6. On success: PATCH the eval request document → `status: "dispatched"`
+ * 7. On failure: PATCH the eval request document → `status: "failed"` + error
+ * 8. Return a structured result
  *
  * ## Sanity Manage Webhook Configuration
  *
@@ -44,38 +48,37 @@
  * @see .github/workflows/external-eval.yml — receiving workflow
  * @see docs/design-docs/report-store/visibility-workflows.md
  */
-/** Projected shape of an `ailf.evalRequest` document from a Sanity webhook. */
+/**
+ * Projected shape of an `ailf.evalRequest` document from a Sanity webhook.
+ *
+ * Per the W0239 schema redesign, request-scope fields (mode, perspective,
+ * tasks, areas, debug, tag, etc.) ride inside the `pipelineRequest` JSON
+ * blob — the canonical `PipelineRequest` serialization. The handler parses
+ * it via `PipelineRequestSchema` from `@sanity/ailf-core` and forwards it
+ * to the dispatcher as-is.
+ */
 export interface EvalRequestPayload {
     /** The Sanity document _id */
     _id: string;
     /** The Sanity document _type (should be "ailf.evalRequest") */
     _type: string;
-    /** Feature areas to scope the evaluation (task-scoped evals) */
-    areas?: string[];
-    /** Sanity dataset */
+    /** Sanity dataset hosting the eval-request document itself */
     dataset: string;
-    /** Run in debug mode */
-    debug?: boolean;
     /** Error message (only if status is "failed") */
     error?: string;
-    /** Evaluation mode */
-    mode: string;
-    /** Content release perspective ID (release-scoped evals) */
-    perspective?: string;
-    /** Sanity project ID */
+    /**
+     * Canonical `PipelineRequest` JSON. Source of truth for the dispatch
+     * payload. Parses against `PipelineRequestSchema` from `@sanity/ailf-core`.
+     */
+    pipelineRequest: string;
+    /** Sanity project ID hosting the eval-request document itself */
     projectId: string;
     /** ISO datetime of when the request was created */
     requestedAt: string;
     /** User ID who requested */
     requestedBy?: string;
-    /** Report ID that triggered this re-run (if any) */
-    sourceReportId?: string;
     /** Request status */
     status: string;
-    /** Publish tag */
-    tag?: string;
-    /** Specific task IDs to evaluate (task-scoped evals) */
-    tasks?: string[];
 }
 /** Configuration for the eval request handler. */
 export interface EvalRequestHandlerConfig {

package/dist/webhook/eval-request-handler.js

@@ -10,21 +10,25 @@
  * Designed to run in any HTTP environment: Cloudflare Workers, Vercel
  * functions, Express, Hono, etc.
  *
- * Supports two scoping modes:
- * - **Release-scoped** — requires `perspective` field
- * - **Task-scoped** — requires `tasks` array (optionally with `areas`)
- *
- * At least one of `perspective` or `tasks` must be present.
+ * The eval-request document carries a canonical `PipelineRequest` JSON
+ * blob in its `pipelineRequest` field (see W0239). The handler parses it
+ * via `PipelineRequestSchema` from `@sanity/ailf-core` and forwards it
+ * to the dispatcher as-is. Scoping (release-scoped via `perspective`,
+ * task-scoped via `tasks`) is asserted on the parsed `PipelineRequest`
+ * — at least one must be present.
  *
  * Flow:
  * 1. Receive eval request payload (from Sanity webhook projection)
- * 2. Validate: must be `ailf.evalRequest` type, `pending` status,
- *    with either `perspective` or `tasks`
- * 3. Dispatch evaluation to GitHub Actions via `repository_dispatch`
- *    with `external-eval` event type and scoped client payload
- * 4. On success: PATCH the eval request document → `status: "dispatched"`
- * 5. On failure: PATCH the eval request document → `status: "failed"` + error
- * 6. Return a structured result
+ * 2. Validate envelope: must be `ailf.evalRequest` type, `pending` status,
+ *    `pipelineRequest` present
+ * 3. Parse + Zod-validate `pipelineRequest` against `PipelineRequestSchema`
+ * 4. Assert scoping: parsed request must have `perspective` or `tasks`
+ * 5. Dispatch evaluation to GitHub Actions via `repository_dispatch`
+ *    with `external-eval` event type — the parsed `PipelineRequest`
+ *    rides as `client_payload.request` unchanged
+ * 6. On success: PATCH the eval request document → `status: "dispatched"`
+ * 7. On failure: PATCH the eval request document → `status: "failed"` + error
+ * 8. Return a structured result
  *
  * ## Sanity Manage Webhook Configuration
  *
@@ -45,6 +49,7 @@
  * @see docs/design-docs/report-store/visibility-workflows.md
  */
 import { createClient } from "@sanity/client";
+import { PipelineRequestSchema } from "../_vendor/ailf-core/index.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -116,18 +121,33 @@ export async function handleEvalRequest(payload, config) {
             requestId,
         };
     }
-    const hasPerspective = !!payload.perspective;
-    const hasTasks = Array.isArray(payload.tasks) && payload.tasks.length > 0;
+    if (!payload.pipelineRequest) {
+        return markFailed("Missing required field: pipelineRequest. The eval-request document " +
+            "must carry a canonical PipelineRequest JSON serialization.");
+    }
+    let parsedRequest;
+    try {
+        parsedRequest = JSON.parse(payload.pipelineRequest);
+    }
+    catch (err) {
+        return markFailed(`pipelineRequest is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parseResult = PipelineRequestSchema.safeParse(parsedRequest);
+    if (!parseResult.success) {
+        return markFailed(`pipelineRequest failed PipelineRequestSchema validation: ${parseResult.error.message}`);
+    }
+    const request = reconcileCallerIdentity(parseResult.data, payload.requestedBy);
+    const hasPerspective = !!request.perspective;
+    const hasTasks = Array.isArray(request.tasks) && request.tasks.length > 0;
     if (!hasPerspective && !hasTasks) {
-        return markFailed("Missing required field: perspective or tasks. " +
-            "Provide a content release perspective for release evals, " +
-            "or a tasks array for task-scoped evals.");
+        return markFailed("pipelineRequest must scope the evaluation: provide either " +
+            "`perspective` (release-scoped) or `tasks` (task-scoped).");
     }
     // -------------------------------------------------------------------------
     // 3. Dispatch evaluation via GitHub Actions
     // -------------------------------------------------------------------------
     const repo = config.githubRepo ?? DEFAULT_REPO;
-    const dispatchResult = await dispatchGitHubEval(repo, payload, config);
+    const dispatchResult = await dispatchGitHubEval(repo, request, config);
     // -------------------------------------------------------------------------
     // 4. Update eval request document status
     // -------------------------------------------------------------------------
@@ -152,46 +172,66 @@ export async function handleEvalRequest(payload, config) {
     // Dispatch failed — mark the document as failed
     return markFailed(dispatchResult.error ?? "Unknown dispatch error");
 }
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Reconcile caller-claimed identity against the trustworthy Sanity write
+ * context.
+ *
+ * The `pipelineRequest` blob is authored by whoever wrote the Sanity
+ * document — a browser writer (App SDK dashboard) can set
+ * `executor.name` / `owner.individual` to any string, including
+ * someone else's. The webhook's only trustworthy identity signal is
+ * `payload.requestedBy` (the Sanity-session-authenticated writer).
+ *
+ * Per D0037, `owner.team` is caller-supplied (the caller knows their
+ * team); `executor.surface` / `executor.type` are caller-supplied.
+ * Identity fields (`executor.name`, `executor.githubActor`,
+ * `owner.individual`) are overwritten or stripped server-side here so
+ * downstream provenance reflects who actually wrote the document, not
+ * what they claimed.
+ *
+ * When `requestedBy` is missing (legacy documents), the executor/owner
+ * identity fields are stripped — the pipeline's server-side detection
+ * fills them as best it can.
+ */
+function reconcileCallerIdentity(request, requestedBy) {
+    const out = { ...request };
+    if (request.executor) {
+        out.executor = {
+            ...request.executor,
+            ...(requestedBy ? { name: requestedBy } : { name: undefined }),
+            githubActor: undefined,
+        };
+    }
+    if (request.owner) {
+        out.owner = {
+            ...request.owner,
+            ...(requestedBy
+                ? { individual: requestedBy }
+                : { individual: undefined }),
+        };
+    }
+    return out;
+}
 /**
  * Dispatch an evaluation via GitHub Actions repository_dispatch.
  *
- * Supports both release-scoped (perspective) and task-scoped (tasks/areas)
- * evaluations. Uses the `external-eval` event type with a client_payload
- * conforming to PipelineRequestSchema. The workflow passes it directly to
- * the CLI via `--config` without field translation.
+ * Forwards the already-validated `PipelineRequest` as-is under
+ * `client_payload.request` — no field translation, no hardcoded
+ * overrides. The workflow passes the request to the CLI via `--config`.
+ *
+ * Workflow-level metadata (`caller_repo`) stays at the top level of
+ * `client_payload` for the workflow to read, separate from the
+ * pipeline-invocation contract.
  */
-async function dispatchGitHubEval(repo, payload, config) {
+async function dispatchGitHubEval(repo, request, config) {
     const url = `${GITHUB_API}/repos/${repo}/dispatches`;
-    const hasPerspective = !!payload.perspective;
-    const hasTasks = Array.isArray(payload.tasks) && payload.tasks.length > 0;
-    const hasAreas = Array.isArray(payload.areas) && payload.areas.length > 0;
-    // Nest the PipelineRequest under `request` to stay within GitHub's
-    // 10-property limit on client_payload. Workflow-level metadata
-    // (caller_repo) stays at the top level for the workflow to read.
     const body = {
         client_payload: {
             caller_repo: "sanity-io/www-sanity-io",
-            request: {
-                dataset: payload.dataset,
-                mode: payload.mode,
-                projectId: payload.projectId,
-                publish: true,
-                source: "production",
-                // Studio-initiated evals always use Content Lake as the task source.
-                // Without this, the pipeline only loads filesystem .task.ts files and
-                // Studio-owned tasks are invisible.
-                taskMode: "content-lake",
-                // Release-scoped fields
-                ...(hasPerspective ? { perspective: payload.perspective } : {}),
-                // Task-scoped fields
-                ...(hasTasks ? { tasks: payload.tasks } : {}),
-                ...(hasAreas ? { areas: payload.areas } : {}),
-                ...(payload.debug ? { debug: true } : {}),
-                ...(payload.tag ? { publishTag: payload.tag } : {}),
-                ...(payload.sourceReportId
-                    ? { sourceReportId: payload.sourceReportId }
-                    : {}),
-            },
+            request,
         },
         event_type: "external-eval",
     };

package/package.json

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