@haystackeditor/cli 0.22.1 → 0.23.0

package/dist/commands/crawl-contract.js

@@ -7,3 +7,7 @@ export const CRAWL_MAX_FINDING_STEPS = 64;
 /** Amendment 9: what a crawl has found so far (`exploring`) or its answer at the budget (`answered`), before the sealed manifest;
  * findings carry no images. A read may pass `waitAfter=<updatedAt>` to be held until the crawl changes (at most CRAWL_WAIT_MAX_MS). */
 export const CRAWL_WAIT_MAX_MS = 25_000;
+/** Amendment 13: the crawl's stand-in coverage, one row per provider, operation, kind and phase with its count in each build
+ * (how many times the copy's calls reached the stand-in across the crawl's preparation and all its replays, not user actions). */
+export const CRAWL_MAX_STAND_IN_ROWS = 200;
+export const CRAWL_MAX_STAND_IN_LINES = 20;

package/dist/commands/verify-onboarding.js

@@ -93,7 +93,7 @@ export function parseOnboardingStatus(value, expected) {
         invalid('its data absences');
     if (!isStrings(value.versionChoices))
         invalid('its version choices');
-    if (!isStrings(value.standIns) || !isStrings(value.unsetProviders))
+    if (!isStrings(value.standIns) || !isStrings(value.unsetProviders) || !isStrings(value.standInGaps))
         invalid('its stand-ins');
     if (value.block !== null)
         parseOnboardingBlock(value.block);
@@ -290,11 +290,15 @@ export function formatOnboarding(status) {
         lines.push('', ...status.dataAbsences.map(absence => chalk.yellow(`Note: ${safe(absence)}`)));
     if (status.versionChoices.length)
         lines.push('', ...status.versionChoices.map(choice => chalk.yellow(`Note: ${safe(choice)}`)));
-    const outside = [...status.standIns, ...status.unsetProviders];
+    const outside = [...status.standIns, ...status.unsetProviders, ...standInGapNotes(status.standInGaps)];
     if (outside.length)
         lines.push('', ...outside.map(note => chalk.yellow(`Note: ${safe(note)}`)));
     return lines.join('\n');
 }
+/** Rule 15(g), amendment 3: a stand-in gap as the sentence every result shows. */
+export function standInGapNotes(gaps) {
+    return gaps.map(gap => `A stand-in could not serve ${gap} while onboarding signed in and did the workflow; the crawl may meet it too.`);
+}
 /** Telemetry: onboarding started, blocked or ready, once per state a command sees. */
 export function reportOnboardingState(status) {
     if (status.state === 'onboarding')

package/dist/commands/verify-precompute.js

@@ -8,7 +8,7 @@ import chalk from 'chalk';
 import { NotLoggedInError, resolveAuthContext } from '../utils/auth.js';
 import { findGitRoot, parseRemoteUrl, } from '../utils/git.js';
 import { resolveVerifyBaseSha } from '../utils/verify-base.js';
-import { HaystackApiError, haystackJson, REPO_NOT_ENTITLED_CODE, SUBSCRIPTION_REQUIRED_CODE, } from '../utils/haystack-api.js';
+import { HaystackApiError, haystackFetch, haystackJson, REPO_NOT_ENTITLED_CODE, SUBSCRIPTION_REQUIRED_CODE, } from '../utils/haystack-api.js';
 import { trackPrecomputeEvent } from '../utils/telemetry.js';
 import { findSecretsInPatch, isSecretBearingPath } from '../utils/secret-paths.js';
 import { startPrecomputeDelivery } from './precompute-delivery.js';
@@ -313,13 +313,45 @@ function precomputeResult(response) {
         return { outcome: 'existing', ...reported };
     throw new PrecomputeFailure('The precompute service returned an invalid response.');
 }
+/** The captured change as the service takes it (CRAWL-V1 amendment 14): uploaded once, content-addressed by its sha256 in
+ * the repository's scope (a HEAD finds an earlier upload; a PUT only when it is missing), and named in the front-half
+ * request by digest and size instead of carried inline. Nothing on the way holds a size limit of its own: tldraw's 13.8 MB
+ * capture was refused at the 8 MiB inline bound (2026-10-02). `force` uploads even when the HEAD found it (a 409 says the
+ * service no longer has it). */
+async function uploadSourcePatch(request, token, signal, force = false) {
+    const gzipped = Buffer.from(request.patchGzBase64, 'base64');
+    const path = `/api/agent/cloud-verifier/source-patches/${request.patchSha256}`
+        + `?owner=${encodeURIComponent(request.owner)}&repository=${encodeURIComponent(request.repository)}`;
+    const found = force ? null : await haystackFetch(path, token, { method: 'HEAD', signal }, [404]);
+    if (found === null || found.status === 404) {
+        await haystackFetch(path, token, { method: 'PUT', headers: { 'Content-Type': 'application/gzip' }, body: gzipped, signal });
+    }
+    return gzipped.byteLength;
+}
+/** One front-half submission of a captured request: the change uploaded (uploadSourcePatch), then the request naming it. A
+ * 409 (the service has no such upload: it expired between the HEAD and the POST) uploads it again and submits once more. */
+async function submitCapture(request, token, signal) {
+    const { patchGzBase64: _inline, ...named } = request;
+    const submit = async (force) => {
+        const patchBytes = await uploadSourcePatch(request, token, signal, force);
+        return haystackJson('/api/agent/cloud-verifier/front-half', token, { method: 'POST',
+            headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ...named, patchBytes }), signal });
+    };
+    try {
+        return await submit(false);
+    }
+    catch (error) {
+        if (!(error instanceof HaystackApiError && error.status === 409))
+            throw error;
+        return submit(true);
+    }
+}
 /** One authenticated submission of the already captured request. No source reads or retries. */
 export const deliverPrecomputeRequest = async (request, signal) => {
     signal.throwIfAborted();
     const auth = await resolveAuthContext({ owner: request.owner, repo: request.repository });
     signal.throwIfAborted();
-    return precomputeResult(await haystackJson('/api/agent/cloud-verifier/front-half', auth.token, { method: 'POST', headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(request), signal }));
+    return precomputeResult(await submitCapture(request, auth.token, signal));
 };
 function readWalkerStatus(value) {
     if (value && typeof value === 'object' && !Array.isArray(value)) {
@@ -426,7 +458,9 @@ export function normalModeFailure(error) {
         if (error.status === 429) {
             return new PrecomputeFailure('Precompute requests are temporarily rate limited. Try again later.');
         }
-        return new PrecomputeFailure(`The precompute request failed (HTTP ${error.status}).`);
+        // With the server's reason (classifyHttpError's message carries it): a refused capture said only "HTTP 400", and tldraw's
+        // could not be told apart from any other refusal (2026-10-02).
+        return new PrecomputeFailure(`The precompute request failed: ${error.message}`);
     }
     // The deadline fired while the POST was in flight. The server may still
     // have accepted the job, so say what happened rather than "failed".
@@ -504,12 +538,7 @@ export async function postPrecomputeCapture(capture, token, deadline) {
     const fetchTimer = setTimeout(() => controller.abort(), remainingMs(deadline));
     let response;
     try {
-        response = await haystackJson('/api/agent/cloud-verifier/front-half', token, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(capture.derivation.request),
-            signal: controller.signal,
-        });
+        response = await submitCapture(capture.derivation.request, token, controller.signal);
     }
     finally {
         clearTimeout(fetchTimer);

package/dist/commands/verify.js

@@ -28,9 +28,9 @@ import { findGitRoot } from '../utils/hooks.js';
 import { resolveAuthContext } from '../utils/auth.js';
 import { classifyHttpError, readWithRetries, SERVICE_SILENCE_LIMIT_MS, ServiceSilentError, transientReadFailure, } from '../utils/haystack-api.js';
 import { GATEWAY_TIMEOUT_MS, gatewayFetch } from './case-batch.js';
-import { CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, CRAWL_WAIT_MAX_MS, } from './crawl-contract.js';
+import { CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, CRAWL_MAX_STAND_IN_LINES, CRAWL_MAX_STAND_IN_ROWS, CRAWL_WAIT_MAX_MS, } from './crawl-contract.js';
 import { captureCheckout, crawlUnavailableText, EXPLICIT_WALL_MS, normalModeFailure, postPrecomputeCapture, } from './verify-precompute.js';
-import { formatOnboarding, onboardingExitCode, readOnboardingStatus, reportOnboardingState, waitForOnboarding } from './verify-onboarding.js';
+import { formatOnboarding, onboardingExitCode, readOnboardingStatus, reportOnboardingState, standInGapNotes, waitForOnboarding } from './verify-onboarding.js';
 const CRAWLS_PATH = '/api/agent/cloud-verifier/crawls';
 /** A held read (waitAfter): the service's hold, then the time any read gets. */
 const HELD_READ_TIMEOUT_MS = CRAWL_WAIT_MAX_MS + GATEWAY_TIMEOUT_MS;
@@ -137,6 +137,16 @@ function checkFinding(value) {
         || (value.images.old !== null && typeof value.images.old !== 'string')
         || (value.images.new !== null && typeof value.images.new !== 'string'))
         invalid('a finding');
+    // Amendment 13: present only when the crawl's worlds ran stand-ins for outside services.
+    if (value.standIns !== undefined && (!isRecord(value.standIns) || !isStrings(value.standIns.old, CRAWL_MAX_STAND_IN_LINES)
+        || !isStrings(value.standIns.new, CRAWL_MAX_STAND_IN_LINES)))
+        invalid('the outside services on a finding\'s path');
+}
+/** Amendment 13: one row of the crawl's stand-in coverage. */
+function isStandInRow(value) {
+    return isRecord(value) && typeof value.provider === 'string' && typeof value.operation === 'string'
+        && (value.kind === 'unsupported' || value.kind === 'mutates') && isMember(value.phase, ['build', 'boot', 'run'])
+        && isCount(value.old) && isCount(value.new);
 }
 function checkSpot(value) {
     if (!isRecord(value) || typeof value.id !== 'string' || typeof value.file !== 'string'
@@ -181,6 +191,11 @@ function checkResults(value, view, what) {
     if (blast !== null && (!isRecord(blast) || !isCount(blast.functions) || !isCount(blast.ran)
         || !isCount(blast.unreached) || !isStrings(blast.nearestUnreached)))
         invalid('its affected functions');
+    const standIns = value.standIns;
+    if (standIns !== undefined && (!isRecord(standIns) || !Array.isArray(standIns.coverage)
+        || standIns.coverage.length > CRAWL_MAX_STAND_IN_ROWS || !standIns.coverage.every(isStandInRow)
+        || !isCount(standIns.omittedRows) || !isStrings(standIns.gaps, CRAWL_MAX_STAND_IN_ROWS)))
+        invalid('its outside-service coverage');
     if (value.error !== null)
         checkError(value.error, 'its error');
 }
@@ -369,6 +384,12 @@ function findingLines(finding, position) {
     const lines = [`  ${position}. ${label}: ${finding.why === null ? 'no reason was recorded.' : safe(finding.why)}`,
         `     Starting from ${safe(finding.start)}:`];
     finding.steps.forEach((step, index) => lines.push(`       ${index + 1}. ${safe(step)}`));
+    // Amendment 13: the outside-service calls on its path, answered by Haystack stand-ins, as the judge read them.
+    const outside = finding.standIns;
+    if (outside && (outside.old.length > 0 || outside.new.length > 0)) {
+        const side = (calls) => (calls.length ? calls.map(safe).join('; ') : 'none');
+        lines.push(chalk.dim('     Outside services on this path, answered by Haystack stand-ins ("unsupported": one it could not serve):'), chalk.dim(`       without your change: ${side(outside.old)}`), chalk.dim(`       with your change: ${side(outside.new)}`));
+    }
     return lines;
 }
 export function formatCrawl(view) {
@@ -418,6 +439,13 @@ export function formatCrawl(view) {
     const blast = published.reach.blast;
     if (blast !== null)
         lines.push(`  ${blast.ran} of ${plural(blast.functions, 'affected function')} ran.`);
+    // Amendment 13: calls to outside services the stand-ins could not serve: the copy's missing coverage, never a finding.
+    const gaps = published.standIns?.gaps ?? [];
+    if (gaps.length > 0) {
+        lines.push('', chalk.bold('Outside services the copy could not imitate'), '  Haystack stand-ins answer these services in the copy, but could not serve these calls, so paths through them', '  did not behave as they would in production (missing coverage, not bugs in your change):');
+        for (const gap of gaps)
+            lines.push(`    ${safe(gap)}`);
+    }
     // Only a finished crawl has proven its cleanup: an answered one is still shutting its machines down (Bugbot).
     if (TERMINAL.has(view.status) && view.totals.cleanupUnproven > 0) {
         lines.push('', chalk.yellow(`  ${plural(view.totals.cleanupUnproven, 'machine')} it used could not be proven shut down.`));
@@ -710,7 +738,7 @@ export async function verifyCommand(options) {
     else {
         console.log(formatCrawl(view));
         const notes = [...(onboarding?.dataAbsences ?? []), ...(onboarding?.versionChoices ?? []), ...(onboarding?.standIns ?? []),
-            ...(onboarding?.unsetProviders ?? [])];
+            ...(onboarding?.unsetProviders ?? []), ...standInGapNotes(onboarding?.standInGaps ?? [])];
         if (notes.length)
             console.log(['', ...notes.map(note => `Note: ${safe(note)}`)].join('\n'));
     }

package/dist/utils/haystack-api.js

@@ -183,6 +183,11 @@ export async function classifyHttpError(response, context) {
     return new HaystackApiError(response.status, `${context}: unexpected response (HTTP ${response.status})${suffix}.`);
 }
 export async function haystackJson(path, token, init = {}, acceptedStatuses = []) {
+    const response = await haystackFetch(path, token, init, acceptedStatuses);
+    return response.json();
+}
+/** An authenticated request whose response is not JSON (a HEAD, an upload): the response itself, or the classified error. */
+export async function haystackFetch(path, token, init = {}, acceptedStatuses = []) {
     const response = await fetch(haystackApiUrl(path), {
         ...init,
         headers: headers(token, init.headers),
@@ -190,7 +195,7 @@ export async function haystackJson(path, token, init = {}, acceptedStatuses = []
     if (!response.ok && !acceptedStatuses.includes(response.status)) {
         throw await classifyHttpError(response, `Haystack API ${path}`);
     }
-    return response.json();
+    return response;
 }
 export async function fetchCliIdentity(token) {
     return haystackJson('/api/cli/me', token);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "haystack verify: run your app with and without a change, and see what the change broke",
   "type": "module",
   "bin": {

package/schemas/verify.v1.json

@@ -288,7 +288,7 @@
     "commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
     "count": { "type": "integer", "minimum": 0 },
     "timestamp": { "type": ["string", "null"], "format": "date-time" },
-    "status": { "enum": ["queued", "preparing", "crawling", "draining", "completed", "incomplete", "cancelled"] },
+    "status": { "enum": ["queued", "preparing", "crawling", "draining", "completed", "prepared", "incomplete", "cancelled"] },
     "stage": { "enum": ["reconcile", "source", "worlds", "blast", "knobs", "prepare", "crawl", "publish", "cleanup"] },
     "spotStage": { "enum": ["resolved", "loaded", "exposed", "activated", "pressed", "observed", "confirmed", "judged"] },
     "reuseValue": { "enum": ["hit", "miss", null] },
@@ -334,9 +334,31 @@
             "old": { "type": ["string", "null"] },
             "new": { "type": ["string", "null"] }
           }
+        },
+        "standIns": {
+          "description": "CRAWL-V1 amendment 13, only when the app's copies answer outside services (sign-in, mail, payments...) with Haystack stand-ins: the calls to them on the path this finding was judged on, per build, one line per distinct call ('<unsupported|mutates> <provider>: <operation>', the phase added in parentheses when not run). 'unsupported': the stand-in could not serve the call, so the copy did not behave as production would there.",
+          "type": "object",
+          "required": ["old", "new"],
+          "properties": {
+            "old": { "type": "array", "maxItems": 20, "items": { "type": "string" } },
+            "new": { "type": "array", "maxItems": 20, "items": { "type": "string" } }
+          }
         }
       }
     },
+    "standInRow": {
+      "description": "CRAWL-V1 amendment 13: one distinct outside-service call the crawl's stand-ins logged, with its count in each build: how many times the copy's calls reached the stand-in across the crawl's preparation and all its replays (double-checks and re-walks included), not how many user actions did.",
+      "type": "object",
+      "required": ["provider", "operation", "kind", "phase", "old", "new"],
+      "properties": {
+        "provider": { "type": "string" },
+        "operation": { "type": "string" },
+        "kind": { "enum": ["unsupported", "mutates"] },
+        "phase": { "enum": ["build", "boot", "run"] },
+        "old": { "$ref": "#/$defs/count" },
+        "new": { "$ref": "#/$defs/count" }
+      }
+    },
     "spot": {
       "description": "One changed spot (one hunk of a changed file) and how far the crawl got with it: the change's product blast radius.",
       "type": "object",
@@ -420,15 +442,25 @@
             }
           }
         },
+        "standIns": {
+          "description": "CRAWL-V1 amendment 13, only when the app's copies answer outside services with Haystack stand-ins: every distinct call the crawl's stand-ins logged, both builds alike (at most 200 rows, the rest counted in omittedRows), and each call a stand-in could not serve as a gap line ('<provider>: <operation> (only without your change|only with your change|with and without your change)'). Gaps are missing coverage of the copy, never findings.",
+          "type": "object",
+          "required": ["coverage", "omittedRows", "gaps"],
+          "properties": {
+            "coverage": { "type": "array", "maxItems": 200, "items": { "$ref": "#/$defs/standInRow" } },
+            "omittedRows": { "$ref": "#/$defs/count" },
+            "gaps": { "type": "array", "maxItems": 200, "items": { "type": "string" } }
+          }
+        },
         "notFinishedInTime": { "$ref": "#/$defs/count" },
         "error": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/error" }] }
       }
     },
     "manifest": {
-      "description": "Present once the crawl is terminal and published.",
+      "description": "Present once the crawl is terminal and published. 'prepared' (CRAWL-V1 amendment 12): the change was built and frozen by the turn-end hook and not crawled.",
       "allOf": [{ "$ref": "#/$defs/results" }],
       "properties": {
-        "status": { "enum": ["completed", "incomplete", "cancelled"] }
+        "status": { "enum": ["completed", "prepared", "incomplete", "cancelled"] }
       }
     },
     "answer": {
@@ -460,6 +492,7 @@
         "updatedAt": { "type": "string", "format": "date-time" },
         "supersededBy": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/runId" }] },
         "cancelRequested": { "type": "boolean" },
+        "mode": { "enum": ["prepare", "crawl"], "description": "CRAWL-V1 amendment 12: 'prepare' builds and freezes only (the turn-end hook); 'crawl' checks the change." },
         "status": { "$ref": "#/$defs/status" },
         "stage": { "$ref": "#/$defs/stage" },
         "clocks": {