@diffci.com/diffci 0.1.10 → 0.1.12

package/action.yml

@@ -1,155 +1,155 @@
-# DiffCI observer - the GitHub Action a third-party repository installs (Phase 02, 2026-08-26).
-#
-# WHAT THIS DOES: analyses one commit range against the checkout the job already has, writes a JSON
-# report to the runner's temp directory, prints a summary to the job log and the job summary, optionally
-# uploads the report as an artifact, and - only when `api-url` and `api-token` are both set - sends that
-# same report to DiffCI. With no token configured nothing leaves the runner at all.
-#
-# WHAT THIS DOES NOT DO, and cannot: run tests, skip tests, cancel a job, re-order steps, write to the
-# repository, comment on a pull request, or set a check status. There is no input below that turns any
-# of that on, because the claim being tested for seven days is that installing DiffCI leaves CI
-# byte-identical, and a flag that could change what CI runs would eventually be set by accident.
-#
-# INSTALL IT AS ITS OWN JOB. A job of its own is what makes the claim structural rather than careful:
-#
-#   jobs:
-#     diffci:
-#       runs-on: ubuntu-latest
-#       continue-on-error: true         # a DiffCI failure must not become the workflow's conclusion
-#       permissions:
-#         contents: read
-#       steps:
-#         - uses: actions/checkout@v4
-#           with:
-#             fetch-depth: 0            # the base commit must exist locally, or DiffCI refuses
+# DiffCI observer - the GitHub Action a third-party repository installs (Phase 02, 2026-08-26).
+#
+# WHAT THIS DOES: analyses one commit range against the checkout the job already has, writes a JSON
+# report to the runner's temp directory, prints a summary to the job log and the job summary, optionally
+# uploads the report as an artifact, and - only when `api-url` and `api-token` are both set - sends that
+# same report to DiffCI. With no token configured nothing leaves the runner at all.
+#
+# WHAT THIS DOES NOT DO, and cannot: run tests, skip tests, cancel a job, re-order steps, write to the
+# repository, comment on a pull request, or set a check status. There is no input below that turns any
+# of that on, because the claim being tested for seven days is that installing DiffCI leaves CI
+# byte-identical, and a flag that could change what CI runs would eventually be set by accident.
+#
+# INSTALL IT AS ITS OWN JOB. A job of its own is what makes the claim structural rather than careful:
+#
+#   jobs:
+#     diffci:
+#       runs-on: ubuntu-latest
+#       continue-on-error: true         # a DiffCI failure must not become the workflow's conclusion
+#       permissions:
+#         contents: read
+#       steps:
+#         - uses: actions/checkout@v4
+#           with:
+#             fetch-depth: 0            # the base commit must exist locally, or DiffCI refuses
 #         - uses: DiffCI/DiffCI.com@<40-character commit sha>
-#
-# `diffci verify-workflow` checks those properties against your own workflow files and exits non-zero
-# if any of them does not hold. Run it before the observation window starts.
-name: DiffCI observer
-description: Observation-only change-aware CI analysis. Runs nothing, changes nothing, skips nothing.
-branding:
-  icon: eye
-  color: gray-dark
-
-inputs:
-  repository-path:
-    description: The checkout to observe. Defaults to the workspace.
-    required: false
-    default: ${{ github.workspace }}
-  base-sha:
-    description: Base commit. Leave empty to derive it from the event (pull request base, push before).
-    required: false
-    default: ""
-  head-sha:
-    description: Head commit. Must be given together with base-sha.
-    required: false
-    default: ""
-  node-version:
-    description: Node version used to run the observer. Only affects this job.
-    required: false
-    default: "22"
-  report-path:
-    description: Where to write the report. Must be outside the checkout. Defaults to RUNNER_TEMP.
-    required: false
-    default: ""
-  redact-paths:
-    description: Replace every file path in the report with a stable 12-character digest.
-    required: false
-    default: "false"
-  upload-artifact:
-    description: Upload the report as a workflow artifact.
-    required: false
-    default: "true"
-  artifact-name:
-    description: Name of the uploaded artifact.
-    required: false
-    default: diffci-observation
-  artifact-retention-days:
-    description: Retention for the uploaded artifact.
-    required: false
-    default: "7"
-  api-url:
-    description: >-
-      DiffCI ingest endpoint. Leave empty and nothing is sent anywhere - the report stays on the runner
-      as an artifact. Must be https.
-    required: false
-    default: ""
-  api-token:
-    description: >-
-      Ingest token for THIS repository, from a repository secret. Pass it as the workflow expression
-      for secrets.DIFFCI_TOKEN, never as a literal. Nothing is sent without it. (This text deliberately
-      does not spell out the expression: GitHub evaluates expressions inside action metadata, and
-      "secrets" is not a context an action file may use - a literal expression here made the whole
-      action fail to load on every run until 2026-09-06.)
-    required: false
-    default: ""
-  fail-on-error:
-    description: >-
-      Fail this step when the observation refuses or errors. Default false, so a DiffCI problem never
-      shows up as a red step in your CI. Turn it on only while debugging an installation.
-    required: false
-    default: "false"
-
-outputs:
-  report-path:
-    description: Absolute path of the written report.
-    value: ${{ steps.observe.outputs.report-path }}
-  status:
-    description: OBSERVED, REFUSED, or ERROR.
-    value: ${{ steps.observe.outputs.status }}
-
-runs:
-  using: composite
-  steps:
-    - name: Set up Node for the observer
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ inputs.node-version }}
-
-    # Installed into the action's own directory, never into the observed repository: nothing here
-    # touches the workspace, its node_modules, or its lockfile. --omit=dev keeps this to TypeScript and
-    # a YAML parser; --ignore-scripts means no dependency of DiffCI's runs code on your runner.
-    - name: Install observer dependencies
-      shell: bash
-      working-directory: ${{ github.action_path }}
-      run: npm ci --omit=dev --no-audit --fund=false --ignore-scripts
-
-    - name: Build observer
-      shell: bash
-      working-directory: ${{ github.action_path }}
-      run: node_modules/.bin/tsc -p tsconfig.client.json
-
-    - name: Observe
-      id: observe
-      shell: bash
-      env:
-        DIFFCI_REPO: ${{ inputs.repository-path }}
-        DIFFCI_BASE: ${{ inputs.base-sha }}
-        DIFFCI_HEAD: ${{ inputs.head-sha }}
-        DIFFCI_OUT: ${{ inputs.report-path }}
-        DIFFCI_REDACT: ${{ inputs.redact-paths }}
-        DIFFCI_FAIL_ON_ERROR: ${{ inputs.fail-on-error }}
-        # Passed through the environment, never on the command line: an argv is visible to every other
-        # process on the runner and shows up in traces. The observer reads these directly and never
-        # prints them.
-        DIFFCI_API_URL: ${{ inputs.api-url }}
-        DIFFCI_TOKEN: ${{ inputs.api-token }}
-      run: |
-        set -euo pipefail
-        args=(observe --repo "$DIFFCI_REPO")
-        if [ -n "$DIFFCI_BASE" ]; then args+=(--base "$DIFFCI_BASE"); fi
-        if [ -n "$DIFFCI_HEAD" ]; then args+=(--head "$DIFFCI_HEAD"); fi
-        if [ -n "$DIFFCI_OUT" ]; then args+=(--out "$DIFFCI_OUT"); fi
-        if [ "$DIFFCI_REDACT" = "true" ]; then args+=(--redact-paths); fi
-        if [ "$DIFFCI_FAIL_ON_ERROR" = "true" ]; then args+=(--fail-on-error); fi
-        node "$GITHUB_ACTION_PATH/dist-client/src/client/cli.js" "${args[@]}"
-
-    - name: Upload observation report
-      if: ${{ inputs.upload-artifact == 'true' && steps.observe.outputs.report-path != '' }}
-      uses: actions/upload-artifact@v4
-      with:
-        name: ${{ inputs.artifact-name }}
-        path: ${{ steps.observe.outputs.report-path }}
-        retention-days: ${{ inputs.artifact-retention-days }}
-        if-no-files-found: warn
+#
+# `diffci verify-workflow` checks those properties against your own workflow files and exits non-zero
+# if any of them does not hold. Run it before the observation window starts.
+name: DiffCI observer
+description: Observation-only change-aware CI analysis. Runs nothing, changes nothing, skips nothing.
+branding:
+  icon: eye
+  color: gray-dark
+
+inputs:
+  repository-path:
+    description: The checkout to observe. Defaults to the workspace.
+    required: false
+    default: ${{ github.workspace }}
+  base-sha:
+    description: Base commit. Leave empty to derive it from the event (pull request base, push before).
+    required: false
+    default: ""
+  head-sha:
+    description: Head commit. Must be given together with base-sha.
+    required: false
+    default: ""
+  node-version:
+    description: Node version used to run the observer. Only affects this job.
+    required: false
+    default: "22"
+  report-path:
+    description: Where to write the report. Must be outside the checkout. Defaults to RUNNER_TEMP.
+    required: false
+    default: ""
+  redact-paths:
+    description: Replace every file path in the report with a stable 12-character digest.
+    required: false
+    default: "false"
+  upload-artifact:
+    description: Upload the report as a workflow artifact.
+    required: false
+    default: "true"
+  artifact-name:
+    description: Name of the uploaded artifact.
+    required: false
+    default: diffci-observation
+  artifact-retention-days:
+    description: Retention for the uploaded artifact.
+    required: false
+    default: "7"
+  api-url:
+    description: >-
+      DiffCI ingest endpoint. Leave empty and nothing is sent anywhere - the report stays on the runner
+      as an artifact. Must be https.
+    required: false
+    default: ""
+  api-token:
+    description: >-
+      Ingest token for THIS repository, from a repository secret. Pass it as the workflow expression
+      for secrets.DIFFCI_TOKEN, never as a literal. Nothing is sent without it. (This text deliberately
+      does not spell out the expression: GitHub evaluates expressions inside action metadata, and
+      "secrets" is not a context an action file may use - a literal expression here made the whole
+      action fail to load on every run until 2026-09-06.)
+    required: false
+    default: ""
+  fail-on-error:
+    description: >-
+      Fail this step when the observation refuses or errors. Default false, so a DiffCI problem never
+      shows up as a red step in your CI. Turn it on only while debugging an installation.
+    required: false
+    default: "false"
+
+outputs:
+  report-path:
+    description: Absolute path of the written report.
+    value: ${{ steps.observe.outputs.report-path }}
+  status:
+    description: OBSERVED, REFUSED, or ERROR.
+    value: ${{ steps.observe.outputs.status }}
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Node for the observer
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+
+    # Installed into the action's own directory, never into the observed repository: nothing here
+    # touches the workspace, its node_modules, or its lockfile. --omit=dev keeps this to TypeScript and
+    # a YAML parser; --ignore-scripts means no dependency of DiffCI's runs code on your runner.
+    - name: Install observer dependencies
+      shell: bash
+      working-directory: ${{ github.action_path }}
+      run: npm ci --omit=dev --no-audit --fund=false --ignore-scripts
+
+    - name: Build observer
+      shell: bash
+      working-directory: ${{ github.action_path }}
+      run: node_modules/.bin/tsc -p tsconfig.client.json
+
+    - name: Observe
+      id: observe
+      shell: bash
+      env:
+        DIFFCI_REPO: ${{ inputs.repository-path }}
+        DIFFCI_BASE: ${{ inputs.base-sha }}
+        DIFFCI_HEAD: ${{ inputs.head-sha }}
+        DIFFCI_OUT: ${{ inputs.report-path }}
+        DIFFCI_REDACT: ${{ inputs.redact-paths }}
+        DIFFCI_FAIL_ON_ERROR: ${{ inputs.fail-on-error }}
+        # Passed through the environment, never on the command line: an argv is visible to every other
+        # process on the runner and shows up in traces. The observer reads these directly and never
+        # prints them.
+        DIFFCI_API_URL: ${{ inputs.api-url }}
+        DIFFCI_TOKEN: ${{ inputs.api-token }}
+      run: |
+        set -euo pipefail
+        args=(observe --repo "$DIFFCI_REPO")
+        if [ -n "$DIFFCI_BASE" ]; then args+=(--base "$DIFFCI_BASE"); fi
+        if [ -n "$DIFFCI_HEAD" ]; then args+=(--head "$DIFFCI_HEAD"); fi
+        if [ -n "$DIFFCI_OUT" ]; then args+=(--out "$DIFFCI_OUT"); fi
+        if [ "$DIFFCI_REDACT" = "true" ]; then args+=(--redact-paths); fi
+        if [ "$DIFFCI_FAIL_ON_ERROR" = "true" ]; then args+=(--fail-on-error); fi
+        node "$GITHUB_ACTION_PATH/dist-client/src/client/cli.js" "${args[@]}"
+
+    - name: Upload observation report
+      if: ${{ inputs.upload-artifact == 'true' && steps.observe.outputs.report-path != '' }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: ${{ steps.observe.outputs.report-path }}
+        retention-days: ${{ inputs.artifact-retention-days }}
+        if-no-files-found: warn

package/dist-client/src/client/cli.js

@@ -13,6 +13,8 @@
  * the observer is exactly what Phase 02 shipped: a local analysis whose output never leaves the runner.
  *
  * Commands:
+ *   init               seed a repository with AI-agent instructions for using DiffCI
+ *   check              agent-friendly alias for observe --no-send
  *   observe            analyse the checkout and write an observation report
  *   verify-savings     run a paired full-versus-selected timing check
  *   verify-workflow    check that a DiffCI job in this repository's workflows cannot affect other jobs
@@ -67,6 +69,8 @@ function observerIdentity() {
         if (existsSync(candidate)) {
             try {
                 const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+                if (parsed.name === "@diffci/observer")
+                    return { version: parsed.version ?? "0.0.0", root: current };
                 if (parsed.name === "@diffci.com/diffci" || parsed.name === "diffci") {
                     let sha;
                     try {
@@ -97,6 +101,106 @@ function defaultReportPath(env) {
     const stamp = env.GITHUB_RUN_ID ? `${env.GITHUB_RUN_ID}-${env.GITHUB_RUN_ATTEMPT ?? "1"}` : String(Date.now());
     return join(base, `diffci-observation-${stamp}.json`);
 }
+const AGENT_INSTRUCTIONS = `# DiffCI Agent Instructions
+
+Use DiffCI as the default CI/CD validation lens before proposing, committing, or opening pull requests.
+
+Default command:
+
+\`\`\`bash
+npx @diffci.com/diffci@latest check
+\`\`\`
+
+What this does:
+
+- analyzes the current checkout and commit range;
+- writes a JSON report outside the repository by default;
+- prints selected tests, fallback reasons, and proposed commands;
+- sends nothing unless an endpoint and token are explicitly configured;
+- runs, skips, cancels, or reorders no tests.
+
+If DiffCI reports \`REFUSED\` or \`ERROR\`, treat that as an installation or analysis issue and continue with the repository's normal test commands. If DiffCI reports a selected command, prefer using it as evidence for what changed, not as permission to skip required CI.
+`;
+const CURSOR_RULE = `---
+description: Use DiffCI as the default CI/CD validation lens
+alwaysApply: true
+---
+
+Before proposing, committing, or opening pull requests, run:
+
+\`\`\`bash
+npx @diffci.com/diffci@latest check
+\`\`\`
+
+DiffCI is observation-only by default. It analyzes the change, writes a report outside the checkout, and sends nothing without explicit configuration. Do not use a DiffCI selection as permission to skip required project CI.
+`;
+const GITHUB_COPILOT_INSTRUCTIONS = `# Repository CI/CD Validation
+
+Use DiffCI as the default change-aware CI/CD validation lens:
+
+\`\`\`bash
+npx @diffci.com/diffci@latest check
+\`\`\`
+
+DiffCI's default agent command is observation-only. It should inform which tests and CI paths are relevant, while the repository's required checks remain authoritative.
+`;
+const DIFFCI_CONFIG = `{
+  "$schema": "https://diffci.com/schemas/diffci.config.schema.json",
+  "agentDefaultCommand": "npx @diffci.com/diffci@latest check",
+  "mode": "observe",
+  "sendReports": false
+}
+`;
+function diffciWorkflow(version) {
+    return `name: DiffCI observation
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  diffci:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx @diffci.com/diffci@${version} check
+`;
+}
+function writeInitFile(repoPath, relativePath, content, force) {
+    const absolutePath = join(repoPath, relativePath);
+    const existed = existsSync(absolutePath);
+    if (existed && !force)
+        return `kept ${relativePath} (already exists)`;
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, content, "utf8");
+    return `${existed ? "overwrote" : "wrote"} ${relativePath}`;
+}
+function runInit(flags, env) {
+    const repoPath = resolve(typeof flags.repo === "string" ? flags.repo : env.GITHUB_WORKSPACE ?? process.cwd());
+    const force = flags.force === true;
+    const includeWorkflow = flags.workflow === true;
+    const identity = observerIdentity();
+    const writes = [
+        writeInitFile(repoPath, "AGENTS.md", AGENT_INSTRUCTIONS, force),
+        writeInitFile(repoPath, "CLAUDE.md", AGENT_INSTRUCTIONS, force),
+        writeInitFile(repoPath, ".cursor/rules/diffci.mdc", CURSOR_RULE, force),
+        writeInitFile(repoPath, ".github/copilot-instructions.md", GITHUB_COPILOT_INSTRUCTIONS, force),
+        writeInitFile(repoPath, "diffci.config.json", DIFFCI_CONFIG, force),
+    ];
+    if (includeWorkflow)
+        writes.push(writeInitFile(repoPath, ".github/workflows/diffci.yml", diffciWorkflow(identity.version), force));
+    console.log(`DiffCI initialized for AI coding agents in ${repoPath}`);
+    for (const write of writes)
+        console.log(`  ${write}`);
+    if (!includeWorkflow)
+        console.log("  skipped .github/workflows/diffci.yml (pass --workflow to add it)");
+    console.log("\nDefault agent command: npx @diffci.com/diffci@latest check");
+    return 0;
+}
 function formatFinding(finding) {
     const where = finding.job ? `${finding.workflow}#${finding.job}` : finding.workflow;
     return `  [${finding.severity}] ${finding.code} (${where})\n      ${finding.message}`;
@@ -112,6 +216,10 @@ function summarise(report) {
     const result = report.result;
     if (result) {
         lines.push(`  verdict: ${result.mode}`);
+        if (result.goScope)
+            lines.push("  Go scope: root module only; nested-module CI remains separate");
+        if (result.vueScope)
+            lines.push(`  Vue suite: ${result.vueScope.packageRoot} (${result.vueScope.testConfig})`);
         lines.push(`  selection: ${result.selectedTests.length}/${result.totalTestCount} test files, from ${result.changedFileCount} changed file(s)`);
         lines.push(`  comparator: a simple path-rule CI would have run ${result.pathBaseline.mode === "FULL" ? "everything" : `${result.pathBaseline.selectedTestCount} test file(s)`}`);
         lines.push(`  graph: ${result.graph.nodes} nodes, confidence ${result.graph.effectiveConfidence ?? result.graph.confidence}`);
@@ -146,6 +254,15 @@ async function runObserve(flags, env) {
         return 2;
     }
     const identity = observerIdentity();
+    let economicsHistory;
+    if (typeof flags["economics-history"] === "string") {
+        try {
+            economicsHistory = JSON.parse(readFileSync(resolve(flags["economics-history"]), "utf8"));
+        }
+        catch {
+            console.warn("DiffCI timing history is unreadable; performing normal analysis.");
+        }
+    }
     const report = await observe({
         repoPath,
         env: env,
@@ -155,6 +272,10 @@ async function runObserve(flags, env) {
         headOverride: typeof flags.head === "string" ? flags.head : undefined,
         redactPaths: flags["redact-paths"] === true,
         reportPath,
+        economicsHistory,
+        economicsJobKey: typeof flags["economics-job"] === "string" ? flags["economics-job"] : undefined,
+        forceAnalysis: flags["force-analysis"] === true,
+        vueAnalysisCacheDir: typeof flags["vue-analysis-cache"] === "string" ? flags["vue-analysis-cache"] : undefined,
     });
     mkdirSync(dirname(reportPath), { recursive: true });
     writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
@@ -341,27 +462,32 @@ async function runPilot(flags, env) {
     console.log(`  markdown: ${markdownPath}`);
     return savings.comparison.fullCommandSucceeded && savings.comparison.selectedCommandSucceeded ? 0 : 1;
 }
-const USAGE = `diffci - observation-only change-aware CI analysis
-
-Usage:
-  diffci pilot --full <command> [--repo <path>] [--out-dir <dir>] [--label <name>]
-  diffci observe [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
-                 [--redact-paths] [--json] [--quiet] [--fail-on-error]
-                 [--api-url <url> --api-token <token>] [--no-send]
-  diffci verify-savings --repo <path> --full <command>
-                         (--selected <command> | --selected-from-report <file>)
-                         --out <file> [--markdown <file>] [--label <name>]
-  diffci verify-workflow [--repo <path>]
-  diffci version
-
-pilot runs observe and verify-savings together, writing reports to ../diffci-output by default.
-observe analyses the checkout and writes one JSON report. It runs nothing and changes nothing.
-verify-savings runs both commands and reports measured paired runtime; it is an opt-in pilot command.
-verify-workflow checks that the job running DiffCI cannot affect any other job, and exits 1 if it can.
-
-The report is sent only when both --api-url and --api-token are given (or DIFFCI_API_URL and
-DIFFCI_TOKEN are set). A failed send is reported and never fails the step - the report is on disk
-either way. Plain http is refused; the token is never printed.
+const USAGE = `diffci - observation-only change-aware CI analysis
+
+Usage:
+  diffci init [--repo <path>] [--workflow] [--force]
+  diffci check [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
+               [--redact-paths] [--json] [--quiet] [--fail-on-error]
+  diffci pilot --full <command> [--repo <path>] [--out-dir <dir>] [--label <name>]
+  diffci observe [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
+                 [--redact-paths] [--json] [--quiet] [--fail-on-error]
+                 [--api-url <url> --api-token <token>] [--no-send]
+  diffci verify-savings --repo <path> --full <command>
+                         (--selected <command> | --selected-from-report <file>)
+                         --out <file> [--markdown <file>] [--label <name>]
+  diffci verify-workflow [--repo <path>]
+  diffci version
+
+init writes AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, and diffci.config.json.
+check is the default AI-agent command: it is observe with sending disabled.
+pilot runs observe and verify-savings together, writing reports to ../diffci-output by default.
+observe analyses the checkout and writes one JSON report. It runs nothing and changes nothing.
+verify-savings runs both commands and reports measured paired runtime; it is an opt-in pilot command.
+verify-workflow checks that the job running DiffCI cannot affect any other job, and exits 1 if it can.
+
+The report is sent only when both --api-url and --api-token are given (or DIFFCI_API_URL and
+DIFFCI_TOKEN are set). A failed send is reported and never fails the step - the report is on disk
+either way. Plain http is refused; the token is never printed.
 `;
 async function main() {
     const { command, flags } = parseArgs(process.argv);
@@ -372,6 +498,12 @@ async function main() {
         return;
     }
     switch (command) {
+        case "init":
+            process.exitCode = runInit(flags, env);
+            return;
+        case "check":
+            process.exitCode = await runObserve({ ...flags, "no-send": true }, env);
+            return;
         case "pilot":
             process.exitCode = await runPilot(flags, env);
             return;

package/dist-client/src/client/economics.js

@@ -0,0 +1,31 @@
+export { economicsContext } from "@diffci.com/core/cache/economics-context";
+/** Economics may decline analysis; it never approves a selection or removes tests. */
+export function evaluateEconomics(raw, context) {
+    const analyze = (reason) => ({ decision: "ANALYZE", reason, contextKey: context.contextKey });
+    if (!raw || typeof raw !== "object")
+        return analyze("No valid timing history");
+    const history = raw;
+    if (history.schema !== "diffci.economics.v1" || !context.repository || !context.jobKey || history.repository !== context.repository || history.jobKey !== context.jobKey || history.contextKey !== context.contextKey || history.observerVersion !== context.observerVersion)
+        return analyze("Timing history does not match this repository, job, configuration or observer");
+    const age = (context.now ?? Date.now()) - Date.parse(String(history.recordedAt));
+    if (!Number.isFinite(age) || age < 0 || age > 48 * 60 * 60 * 1000)
+        return analyze("Timing history is stale or future-dated; resample analysis");
+    if (!Array.isArray(history.samples) || history.samples.length < 5 || history.samples.length > 100)
+        return analyze("Five to one hundred historical samples are required");
+    const heads = new Set();
+    let maximumGrossSavedMs = 0;
+    let minimumObserverMs = Infinity;
+    for (const sample of history.samples) {
+        if (!sample || typeof sample !== "object" || sample.stable !== true || typeof sample.headSha !== "string" || !/^[a-f0-9]{40}$/.test(sample.headSha) || ![sample.fullMs, sample.policyMs, sample.observerMs].every(value => typeof value === "number" && Number.isFinite(value) && value > 0))
+            return analyze("History contains an invalid or unstable sample");
+        heads.add(sample.headSha);
+        maximumGrossSavedMs = Math.max(maximumGrossSavedMs, sample.fullMs - sample.policyMs);
+        minimumObserverMs = Math.min(minimumObserverMs, sample.observerMs);
+    }
+    if (heads.size < 5)
+        return analyze("History needs five distinct commits");
+    // Use the best historical gross saving and cheapest observer, with headroom.
+    // This is a cost heuristic, never a correctness claim about the next change.
+    const bypass = maximumGrossSavedMs * 1.25 + 250 < minimumObserverMs;
+    return { decision: bypass ? "BYPASS_FULL" : "ANALYZE", reason: bypass ? "Historical avoided test work does not cover observer cost; retain the full CI job" : "Historical savings may cover analysis; measure this change", contextKey: context.contextKey, sampleCount: history.samples.length, maximumGrossSavedMs, minimumObserverMs };
+}