@tangle-network/agent-eval 0.190.0 → 0.191.0

package/dist/search-shipper-C55V7HE3.js

@@ -0,0 +1,781 @@
+import { o as SearchLedgerIntegrityError } from "./search-ledger-file-EvdDZRhv.js";
+import { r as parseSearchLedgerLine } from "./search-ledger-CQ8Uy4FK.js";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { fileURLToPath } from "node:url";
+import { open, readFile } from "node:fs/promises";
+//#region src/hosted/types.ts
+/**
+* # Hosted-tier wire format: the shapes every orchestrator (ours, a partner's
+* self-hosted one, a future open implementation) must accept.
+*
+* This package implements exactly one wire version. Servers reject every
+* other version instead of translating old payloads.
+*
+* The wire carries two streams in one transport:
+*
+*   1. **Search ledgers** (`/v1/search-blobs/*`, `/v1/ingest/search-ledger`).
+*      A producer ships a search's hash-chained ledger lines and the blobs
+*      they name; `./search-ledger-wire.ts` owns those shapes.
+*
+*   2. **Trace spans** (`POST /v1/ingest/traces`). Standard OTLP-shaped
+*      spans with a few additional attributes so the orchestrator can
+*      pivot from a search cell to its underlying execution. Compatible
+*      with any OTel collector.
+*
+* Every endpoint is authenticated with a bearer token and a tenant id
+* header. Tenants isolate everything downstream of ingest; no tenant
+* ever sees another tenant's data.
+*/
+const HOSTED_WIRE_VERSION = "2026-07-24.v1";
+//#endregion
+//#region src/hosted/schemas.ts
+const finiteNumber = z.number().finite();
+const nonNegativeInteger = z.number().int().nonnegative();
+const nonEmptyString = z.string().min(1).refine((value) => value.trim().length > 0, "must not be blank");
+const attributeValue = z.union([
+	z.string(),
+	finiteNumber,
+	z.boolean()
+]);
+const attributes = z.record(z.string(), attributeValue);
+const UINT64_MAX = 18446744073709551615n;
+const UnixNanoTimestampSchema = z.string().regex(/^(0|[1-9][0-9]*)$/, "expected an unsigned base-10 integer string").refine((value) => BigInt(value) <= UINT64_MAX, "must fit in an unsigned 64-bit integer");
+const TraceSpanEventEntrySchema = z.object({
+	timeUnixNano: UnixNanoTimestampSchema,
+	name: nonEmptyString,
+	attributes: attributes.optional()
+}).strict();
+const TraceSpanEventSchema = z.object({
+	traceId: nonEmptyString,
+	spanId: nonEmptyString,
+	parentSpanId: nonEmptyString.optional(),
+	name: nonEmptyString,
+	startTimeUnixNano: UnixNanoTimestampSchema,
+	endTimeUnixNano: UnixNanoTimestampSchema,
+	attributes,
+	events: z.array(TraceSpanEventEntrySchema).optional(),
+	status: z.object({
+		code: z.enum([
+			"OK",
+			"ERROR",
+			"UNSET"
+		]),
+		message: z.string().optional()
+	}).strict().optional(),
+	"tangle.runId": nonEmptyString.optional(),
+	"tangle.generation": nonNegativeInteger.optional(),
+	"tangle.cellId": nonEmptyString.optional(),
+	"tangle.scenarioId": nonEmptyString.optional()
+}).strict().refine((span) => BigInt(span.endTimeUnixNano) >= BigInt(span.startTimeUnixNano), {
+	path: ["endTimeUnixNano"],
+	message: "endTimeUnixNano must be greater than or equal to startTimeUnixNano"
+});
+z.object({
+	wireVersion: z.literal(HOSTED_WIRE_VERSION),
+	spans: z.array(z.unknown())
+}).strict();
+const IngestTracesRequestSchema = z.object({
+	wireVersion: z.literal(HOSTED_WIRE_VERSION),
+	spans: z.array(TraceSpanEventSchema)
+}).strict();
+const IngestResponseSchema = z.object({
+	accepted: nonNegativeInteger,
+	rejected: z.array(z.object({
+		index: nonNegativeInteger,
+		reason: nonEmptyString
+	}).strict())
+}).strict();
+//#endregion
+//#region src/hosted/search-ledger-wire.ts
+/**
+* The search-ledger wire: how a producer ships a search ledger to a hosted
+* store, and the rule a store applies to each batch.
+*
+* A producer ships three things, in this order:
+*
+*   1. Blobs: `PUT /v1/search-blobs/<sha256 hex>` with the exact bytes an
+*      entry's artifact ref names. The store re-hashes them; the call is
+*      idempotent by content.
+*   2. Head: `GET /v1/ingest/search-ledger/<searchId>/head` tells a restarted
+*      producer where the store's copy of the chain ends.
+*   3. Entries: `POST /v1/ingest/search-ledger` with canonical ledger lines,
+*      starting at `fromSequence`. The store verifies every line, links it to
+*      its stored head, and answers with its new head.
+*
+* The lines are the ledger's own bytes, so producer and store hash identical
+* input. A line below the store's head with an equal hash is a no-op; a
+* different hash is a fork (`409 chain_conflict`); a batch that starts past
+* the head is a gap (`409 sequence_gap`). Both 409s carry the store's head,
+* so a producer resends from there or stops on a fork.
+*/
+/** At most this many lines in one ingest request. */
+const SEARCH_LEDGER_BATCH_MAX_LINES = 1e3;
+/** At most this many UTF-8 bytes across one request's lines. A single line
+* larger than this cannot be shipped. */
+const SEARCH_LEDGER_BATCH_MAX_BYTES = 1048576;
+const SEARCH_LEDGER_INGEST_PATH = "/v1/ingest/search-ledger";
+function searchLedgerHeadPath(searchId) {
+	return `${SEARCH_LEDGER_INGEST_PATH}/${encodeURIComponent(searchId)}/head`;
+}
+/** Blobs are addressed by the hex digest alone. */
+function searchBlobPath(sha256) {
+	return `/v1/search-blobs/${sha256.slice(7)}`;
+}
+const HASH = z.custom((value) => typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value), "expected sha256:<64 lowercase hex characters>");
+const SEARCH_ID = z.string().min(1).refine((value) => value.trim() === value, "must not contain surrounding whitespace");
+const SEQUENCE = z.number().int().nonnegative().safe();
+/** What the run is for: an optimization, or an eval (a one-node search). */
+const SearchRunKindSchema = z.enum(["optimization", "eval"]);
+/** Where a store's copy of one search's chain ends. `headHash` is null exactly
+* when the store holds no entry. */
+const SearchLedgerHeadSchema = z.object({
+	searchId: SEARCH_ID,
+	nextSequence: SEQUENCE,
+	headHash: HASH.nullable()
+}).strict().refine((head) => head.nextSequence === 0 === (head.headHash === null), {
+	message: "headHash must be null exactly when nextSequence is 0",
+	path: ["headHash"]
+});
+const IngestSearchLedgerRequestSchema = z.object({
+	wireVersion: z.literal(HOSTED_WIRE_VERSION),
+	searchId: SEARCH_ID,
+	runKind: SearchRunKindSchema,
+	fromSequence: SEQUENCE,
+	lines: z.array(z.string().min(1)).min(1).max(SEARCH_LEDGER_BATCH_MAX_LINES)
+}).strict().superRefine((request, ctx) => {
+	const bytes = searchLedgerLinesByteLength(request.lines);
+	if (bytes > 1048576) ctx.addIssue({
+		code: "custom",
+		path: ["lines"],
+		message: `lines hold ${bytes} bytes; at most ${SEARCH_LEDGER_BATCH_MAX_BYTES} per request`
+	});
+});
+/** The body of a `409`: a fork or a gap, with the store's head. */
+const SearchLedgerConflictSchema = z.object({
+	error: z.enum(["chain_conflict", "sequence_gap"]),
+	message: z.string().min(1),
+	head: SearchLedgerHeadSchema
+}).strict();
+/** What a store kept of one blob. `masked` and `withheld` come from the
+* store's own redaction scan or the tenant's content posture. */
+const SearchBlobPutResponseSchema = z.object({
+	sha256: HASH,
+	byteLength: SEQUENCE,
+	state: z.enum([
+		"stored",
+		"masked",
+		"withheld"
+	])
+}).strict();
+const UTF8 = new TextEncoder();
+function searchLedgerLinesByteLength(lines) {
+	let bytes = 0;
+	for (const line of lines) bytes += UTF8.encode(line).byteLength;
+	return bytes;
+}
+/** Every blob an event names, once each. Ship these before the event. */
+function searchLedgerArtifactRefs(event) {
+	const refs = [...event.artifacts];
+	switch (event.kind) {
+		case "node-registered":
+			refs.push(event.artifact, ...event.surfaces.map((surface) => surface.artifact));
+			break;
+		case "edge-recorded":
+			for (const ref of [event.rationale, ...event.diffs]) if ("uri" in ref) refs.push(ref);
+			break;
+		case "cell-settled":
+			for (const evidence of event.surfaceEvidence) refs.push(...evidence.evidence);
+			break;
+		default: break;
+	}
+	const unique = /* @__PURE__ */ new Map();
+	for (const ref of refs) if (!unique.has(ref.sha256)) unique.set(ref.sha256, ref);
+	return [...unique.values()];
+}
+/**
+* Apply the wire's chain rule to one batch. Each line is verified in isolation
+* (`parseSearchLedgerLine`) and linked to the stored head. A malformed line
+* throws `SearchLedgerIntegrityError`, which a store answers with 422; the
+* state machine (`SearchState`) runs after admission, on `entries`.
+*/
+function admitSearchLedgerBatch(input) {
+	const { request, head } = input;
+	if (request.searchId !== head.searchId) throw new Error(`head is for search ${head.searchId}, request is for ${request.searchId}`);
+	if (request.fromSequence > head.nextSequence) return conflict("sequence_gap", `batch starts at sequence ${request.fromSequence}; the store expects ${head.nextSequence}`, head);
+	const entries = [];
+	const lines = [];
+	let previousHash = head.headHash;
+	for (let index = 0; index < request.lines.length; index++) {
+		const sequence = request.fromSequence + index;
+		const line = request.lines[index];
+		const entry = parseSearchLedgerLine(line, request.searchId, {
+			path: `search ${request.searchId}`,
+			line: sequence + 1
+		});
+		if (entry.sequence !== sequence) throw new SearchLedgerIntegrityError(`line ${index} of the batch holds sequence ${entry.sequence}, expected ${sequence}`);
+		if (sequence < head.nextSequence) {
+			if (input.storedEntryHash(sequence) !== entry.entryHash) return conflict("chain_conflict", `sequence ${sequence} differs from the stored entry; the ledger forked`, head);
+			continue;
+		}
+		if (entry.previousHash !== previousHash) {
+			if (sequence === head.nextSequence) return conflict("chain_conflict", `sequence ${sequence} does not extend the stored head; the ledger forked`, head);
+			throw new SearchLedgerIntegrityError(`sequence ${sequence} does not extend sequence ${sequence - 1} in the same batch`);
+		}
+		entries.push(entry);
+		lines.push(line);
+		previousHash = entry.entryHash;
+	}
+	const last = entries.at(-1);
+	return {
+		status: "accepted",
+		entries,
+		lines,
+		head: last ? {
+			searchId: head.searchId,
+			nextSequence: last.sequence + 1,
+			headHash: last.entryHash
+		} : head
+	};
+}
+function conflict(error, message, head) {
+	return {
+		status: "conflict",
+		conflict: {
+			error,
+			message,
+			head
+		}
+	};
+}
+//#endregion
+//#region src/hosted/client.ts
+/** A request the server refused, after any retries. */
+var HostedRequestError = class extends Error {
+	status;
+	body;
+	constructor(url, status, body) {
+		super(`hosted ${url} failed (${status}): ${body.slice(0, 500)}`);
+		this.name = "HostedRequestError";
+		this.status = status;
+		this.body = body;
+	}
+};
+const MAX_IDEMPOTENCY_KEY_LENGTH = 256;
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) return reject(signal.reason);
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** `Retry-After` as milliseconds: delay-seconds or an HTTP date. Null when
+* absent or unreadable, so the caller falls back to its own backoff. */
+function retryAfterMs(value, now = Date.now()) {
+	if (value === null) return null;
+	const trimmed = value.trim();
+	if (/^\d+$/.test(trimmed)) return Number(trimmed) * 1e3;
+	const at = Date.parse(trimmed);
+	return Number.isFinite(at) ? Math.max(0, at - now) : null;
+}
+function backoffMs(attempt) {
+	return 2 ** attempt * 200 + Math.random() * 200;
+}
+function normalizeHostedBase(endpoint) {
+	return endpoint.trim().replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+function resolveIdempotencyKey(key) {
+	const resolved = key ?? globalThis.crypto.randomUUID();
+	if (resolved.trim().length === 0) throw new Error("idempotency key must not be blank");
+	if (resolved.length > MAX_IDEMPOTENCY_KEY_LENGTH) throw new Error(`idempotency key must be at most ${MAX_IDEMPOTENCY_KEY_LENGTH} characters`);
+	return resolved;
+}
+function isRetryable(status) {
+	return status >= 500 || status === 408 || status === 429;
+}
+async function send(tenant, request) {
+	const timeoutMs = tenant.timeoutMs ?? 3e4;
+	const maxRetries = tenant.retries ?? 2;
+	const f = tenant.fetchImpl ?? ((...args) => fetch(...args));
+	const url = `${normalizeHostedBase(tenant.endpoint)}${request.path}`;
+	const headers = {
+		authorization: `Bearer ${tenant.apiKey}`,
+		"x-tangle-tenant-id": tenant.tenantId,
+		"x-tangle-wire-version": HOSTED_WIRE_VERSION
+	};
+	if (request.method !== "GET") {
+		headers["idempotency-key"] = resolveIdempotencyKey(request.idempotencyKey);
+		headers["content-type"] = request.contentType ?? "application/json";
+	}
+	let lastError;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		const timeout = AbortSignal.timeout(timeoutMs);
+		const signal = request.signal ? AbortSignal.any([request.signal, timeout]) : timeout;
+		let res;
+		try {
+			res = await f(url, {
+				method: request.method,
+				headers,
+				...request.body === void 0 ? {} : { body: request.body },
+				signal
+			});
+		} catch (err) {
+			if (request.signal?.aborted) throw err;
+			lastError = err;
+			if (attempt === maxRetries) throw err;
+			await sleep(backoffMs(attempt), request.signal);
+			continue;
+		}
+		if (!res.ok && !request.expected?.includes(res.status)) {
+			const text = await res.text().catch(() => "");
+			const error = new HostedRequestError(url, res.status, text);
+			if (!isRetryable(res.status) || attempt === maxRetries) throw error;
+			lastError = error;
+			await sleep(retryAfterMs(res.headers.get("retry-after")) ?? backoffMs(attempt), request.signal);
+			continue;
+		}
+		try {
+			return {
+				status: res.status,
+				json: await res.json(),
+				url
+			};
+		} catch (error) {
+			throw new Error(`hosted ${url} returned invalid JSON`, { cause: error });
+		}
+	}
+	throw lastError ?? /* @__PURE__ */ new Error("hosted request exhausted retries");
+}
+function parseResponse(schema, value, url) {
+	const parsed = schema.safeParse(value);
+	if (parsed.success) return parsed.data;
+	const reason = parsed.error.issues.map((issue) => `${issue.path.map(String).join(".") || "value"}: ${issue.message}`).join("; ");
+	throw new Error(`hosted ${url} returned an invalid response: ${reason}`);
+}
+function createHostedClient(tenant) {
+	if (normalizeHostedBase(tenant.endpoint).length === 0) throw new Error("endpoint is required");
+	if (tenant.apiKey.trim().length === 0) throw new Error("apiKey is required");
+	if (tenant.tenantId.trim().length === 0) throw new Error("tenantId is required");
+	if (tenant.timeoutMs !== void 0 && (!Number.isFinite(tenant.timeoutMs) || tenant.timeoutMs <= 0)) throw new Error("timeoutMs must be greater than 0");
+	if (tenant.retries !== void 0 && (!Number.isInteger(tenant.retries) || tenant.retries < 0)) throw new Error("retries must be a non-negative integer");
+	return {
+		tenant,
+		wireVersion: HOSTED_WIRE_VERSION,
+		async ingestTraces(spans, idempotencyKey) {
+			const body = IngestTracesRequestSchema.parse({
+				wireVersion: HOSTED_WIRE_VERSION,
+				spans
+			});
+			const res = await send(tenant, {
+				method: "POST",
+				path: "/v1/ingest/traces",
+				body: JSON.stringify(body),
+				idempotencyKey
+			});
+			return parseResponse(IngestResponseSchema, res.json, res.url);
+		},
+		async searchLedgerHead(searchId, signal) {
+			const res = await send(tenant, {
+				method: "GET",
+				path: searchLedgerHeadPath(searchId),
+				signal
+			});
+			const head = parseResponse(SearchLedgerHeadSchema, res.json, res.url);
+			if (head.searchId !== searchId) throw new Error(`hosted ${res.url} returned the head of search ${head.searchId}`);
+			return head;
+		},
+		async ingestSearchLedger(request, signal) {
+			const body = IngestSearchLedgerRequestSchema.parse(request);
+			const last = body.lines.at(-1);
+			const res = await send(tenant, {
+				method: "POST",
+				path: SEARCH_LEDGER_INGEST_PATH,
+				body: JSON.stringify(body),
+				idempotencyKey: `search-ledger:${await sha256Hex(`${body.searchId}\n${body.runKind}\n${body.fromSequence}\n${body.lines.length}\n${last}`)}`,
+				signal,
+				expected: [409]
+			});
+			if (res.status === 409) return {
+				status: "conflict",
+				conflict: parseResponse(SearchLedgerConflictSchema, res.json, res.url)
+			};
+			return {
+				status: "accepted",
+				head: parseResponse(SearchLedgerHeadSchema, res.json, res.url)
+			};
+		},
+		async putSearchBlob(sha256, bytes, contentType, signal) {
+			const res = await send(tenant, {
+				method: "PUT",
+				path: searchBlobPath(sha256),
+				body: bytes,
+				contentType,
+				idempotencyKey: `search-blob:${sha256}`,
+				signal
+			});
+			const stored = parseResponse(SearchBlobPutResponseSchema, res.json, res.url);
+			if (stored.sha256 !== sha256) throw new Error(`hosted ${res.url} acknowledged blob ${stored.sha256}, sent ${sha256}`);
+			return stored;
+		}
+	};
+}
+async function sha256Hex(text) {
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+* Build a {@link HostedTenant} from env, or `undefined` when ingest is not
+* configured, so a product wires it unconditionally and it stays off until the
+* env is set. Env precedence:
+*   - endpoint:  `TANGLE_INGEST_URL` → `TANGLE_ORCHESTRATOR_URL`
+*   - apiKey:    `TANGLE_INGEST_API_KEY` → `TANGLE_API_KEY`
+*   - tenantId:  `TANGLE_TENANT_ID`
+* A trailing slash on the endpoint is stripped. `overrides` win over env.
+*/
+function hostedTenantFromEnv(overrides = {}) {
+	const env = overrides.env ?? process.env;
+	const endpoint = (overrides.endpoint ?? env.TANGLE_INGEST_URL ?? env.TANGLE_ORCHESTRATOR_URL)?.trim();
+	const apiKey = (overrides.apiKey ?? env.TANGLE_INGEST_API_KEY ?? env.TANGLE_API_KEY)?.trim();
+	const tenantId = (overrides.tenantId ?? env.TANGLE_TENANT_ID)?.trim();
+	if (!endpoint || !apiKey || !tenantId) return void 0;
+	const tenant = {
+		endpoint: endpoint.replace(/\/+$/, ""),
+		apiKey,
+		tenantId
+	};
+	if (overrides.fetchImpl) tenant.fetchImpl = overrides.fetchImpl;
+	if (overrides.timeoutMs !== void 0) tenant.timeoutMs = overrides.timeoutMs;
+	if (overrides.retries !== void 0) tenant.retries = overrides.retries;
+	return tenant;
+}
+/** {@link createHostedClient} over {@link hostedTenantFromEnv}; `undefined`
+* when ingest is not configured. */
+function hostedClientFromEnv(overrides = {}) {
+	const tenant = hostedTenantFromEnv(overrides);
+	return tenant ? createHostedClient(tenant) : void 0;
+}
+//#endregion
+//#region src/hosted/search-shipper.ts
+/**
+* Ship a search ledger to a hosted store while the search runs, or after.
+*
+* The local ledger is the source of truth and the search never waits on the
+* network: the shipper reads the ledger file the recorder already made
+* durable, uploads the blobs each entry names, then posts the entries. It
+* starts from the store's head, so a restarted process, a lost response, or a
+* second shipper continues where the store's chain ends instead of resending
+* the search. A store that holds a different chain for the same search stops
+* the shipper with `SearchShipConflictError`; nothing is overwritten.
+*/
+/** The store holds a different chain for this search. */
+var SearchShipConflictError = class extends Error {
+	conflict;
+	constructor(conflict) {
+		super(`search ${conflict.head.searchId}: ${conflict.error}: ${conflict.message} (store head ${conflict.head.nextSequence} ${conflict.head.headHash ?? "empty"})`);
+		this.name = "SearchShipConflictError";
+		this.conflict = conflict;
+	}
+};
+/** Ship every complete line of the ledger file now, then return. */
+async function shipSearchLedger(options) {
+	return new SearchLedgerTail(options).ship();
+}
+/**
+* Tail the ledger: ship new lines every `intervalMs` (default 2 s) until
+* `stop()`. A transient failure is kept on `lastError` and retried on the next
+* tick; a conflict stops tailing and is thrown by `stop()`.
+*/
+function startSearchShipper(options) {
+	const tail = new SearchLedgerTail(options);
+	const intervalMs = options.intervalMs ?? 2e3;
+	const stopping = new AbortController();
+	let lastError = null;
+	let conflict = null;
+	let running = Promise.resolve();
+	const tick = () => {
+		running = running.then(async () => {
+			if (conflict) return;
+			try {
+				await tail.ship();
+				lastError = null;
+			} catch (error) {
+				if (error instanceof SearchShipConflictError) conflict = error;
+				else lastError = error instanceof Error ? error : new Error(String(error));
+			}
+		});
+		return running;
+	};
+	const loop = (async () => {
+		while (!stopping.signal.aborted && !conflict) {
+			await tick();
+			await new Promise((resolve) => {
+				const timer = setTimeout(resolve, intervalMs);
+				stopping.signal.addEventListener("abort", () => {
+					clearTimeout(timer);
+					resolve();
+				}, { once: true });
+			});
+		}
+	})();
+	return {
+		get lastError() {
+			return lastError;
+		},
+		async flush() {
+			await tick();
+			if (conflict) throw conflict;
+			if (lastError) throw lastError;
+			return tail.result();
+		},
+		async stop() {
+			stopping.abort();
+			await loop;
+			await running;
+			if (conflict) throw conflict;
+			return tail.ship();
+		}
+	};
+}
+/** One full batch of lines with their newlines, plus a byte to see where a
+* maximal line ends. */
+const READ_CHUNK_BYTES = 1049577;
+var SearchLedgerTail = class {
+	client;
+	options;
+	content;
+	/** Where the store's chain ends, and the byte offset of that line locally. */
+	head = null;
+	offset = 0;
+	localLines = 0;
+	uploaded = /* @__PURE__ */ new Set();
+	missing = /* @__PURE__ */ new Map();
+	counts = {
+		linesPosted: 0,
+		batches: 0,
+		gapResends: 0,
+		uploaded: 0,
+		stored: 0,
+		masked: 0,
+		withheld: 0
+	};
+	constructor(options) {
+		this.options = options;
+		this.content = options.content ?? "full";
+		this.client = createHostedClient(options.tenant);
+	}
+	result() {
+		const { linesPosted, batches, gapResends, uploaded, stored, masked, withheld } = this.counts;
+		return {
+			searchId: this.options.ledger.searchId,
+			head: this.head ?? {
+				searchId: this.options.ledger.searchId,
+				nextSequence: 0,
+				headHash: null
+			},
+			localLines: this.localLines,
+			linesPosted,
+			batches,
+			gapResends,
+			blobs: {
+				content: this.content,
+				uploaded,
+				stored,
+				masked,
+				withheld,
+				missing: [...this.missing.values()]
+			}
+		};
+	}
+	async ship() {
+		const { signal } = this.options;
+		if (this.head === null) await this.syncTo(await this.client.searchLedgerHead(this.options.ledger.searchId, signal));
+		for (;;) {
+			const lines = await this.readChunk(this.offset, this.head);
+			if (lines.length === 0) return this.result();
+			const batch = takeBatch(lines);
+			if (this.content === "full") await this.uploadBlobs(batch);
+			const fromSequence = this.head.nextSequence;
+			const outcome = await this.client.ingestSearchLedger({
+				wireVersion: HOSTED_WIRE_VERSION,
+				searchId: this.options.ledger.searchId,
+				runKind: this.options.runKind,
+				fromSequence,
+				lines: batch.map((line) => line.text)
+			}, signal);
+			this.counts.batches++;
+			this.counts.linesPosted += batch.length;
+			if (outcome.status === "conflict") {
+				if (outcome.conflict.error === "chain_conflict") throw new SearchShipConflictError(outcome.conflict);
+				this.counts.gapResends++;
+				await this.syncTo(outcome.conflict.head);
+				continue;
+			}
+			const last = batch.at(-1).entry;
+			if (outcome.head.nextSequence < last.sequence + 1 || outcome.head.nextSequence === last.sequence + 1 && outcome.head.headHash !== last.entryHash) throw new Error(`store acknowledged sequence ${fromSequence}..${last.sequence} with head ${outcome.head.nextSequence} ${outcome.head.headHash}`);
+			await this.syncTo(outcome.head);
+		}
+	}
+	/** Move the cursor to the store's head, checking that the local ledger holds
+	* the same entry there. A different entry is a fork; a store ahead of the
+	* local file holds lines this ledger never wrote. */
+	async syncTo(head) {
+		if (head.searchId !== this.options.ledger.searchId) throw new Error(`store answered for search ${head.searchId}`);
+		const fork = (message) => new SearchShipConflictError({
+			error: "chain_conflict",
+			message,
+			head
+		});
+		const empty = {
+			searchId: head.searchId,
+			nextSequence: 0,
+			headHash: null
+		};
+		const forward = this.head !== null && head.nextSequence >= this.head.nextSequence;
+		let offset = forward ? this.offset : 0;
+		let cursor = forward ? this.head : empty;
+		while (cursor.nextSequence < head.nextSequence) {
+			const lines = await this.readChunk(offset, cursor);
+			if (lines.length === 0) throw fork(`the store holds ${head.nextSequence} entries; the local ledger holds ${cursor.nextSequence}`);
+			const take = Math.min(lines.length, head.nextSequence - cursor.nextSequence);
+			for (let index = 0; index < take; index++) offset += lines[index].bytes;
+			const last = lines[take - 1].entry;
+			cursor = {
+				searchId: head.searchId,
+				nextSequence: last.sequence + 1,
+				headHash: last.entryHash
+			};
+		}
+		if (cursor.headHash !== head.headHash) throw fork(`the store's entry ${head.nextSequence - 1} differs from the local ledger's`);
+		this.offset = offset;
+		this.head = head;
+	}
+	/** The complete lines in one read chunk from `offset`, checked to continue
+	* the chain at `head`. A chunk holds at least one full batch. */
+	async readChunk(offset, head) {
+		const bytes = await readRange(this.options.ledger.path, offset, READ_CHUNK_BYTES);
+		const lines = [];
+		let start = 0;
+		let expectedSequence = head.nextSequence;
+		let previousHash = head.headHash;
+		for (;;) {
+			const newline = bytes.indexOf(10, start);
+			if (newline < 0) break;
+			const text = bytes.toString("utf8", start, newline);
+			const entry = JSON.parse(text);
+			if (entry.searchId !== this.options.ledger.searchId || entry.sequence !== expectedSequence || entry.previousHash !== previousHash) throw new Error(`${this.options.ledger.path} line ${expectedSequence + 1} does not continue the chain at sequence ${expectedSequence}`);
+			lines.push({
+				text,
+				entry,
+				bytes: newline + 1 - start
+			});
+			expectedSequence++;
+			previousHash = entry.entryHash;
+			start = newline + 1;
+		}
+		if (lines.length === 0 && bytes.byteLength === READ_CHUNK_BYTES) throw new Error(`${this.options.ledger.path} line ${expectedSequence + 1} is longer than ${SEARCH_LEDGER_BATCH_MAX_BYTES} bytes; one request carries at most that`);
+		this.localLines = Math.max(this.localLines, expectedSequence);
+		return lines;
+	}
+	async uploadBlobs(batch) {
+		for (const line of batch) for (const ref of searchLedgerArtifactRefs(line.entry.event)) {
+			if (this.uploaded.has(ref.sha256) || this.missing.has(ref.sha256)) continue;
+			const bytes = await readBlob(ref.uri);
+			if (typeof bytes === "string") {
+				this.missing.set(ref.sha256, {
+					sha256: ref.sha256,
+					uri: ref.uri,
+					reason: bytes
+				});
+				continue;
+			}
+			const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+			if (digest !== ref.sha256 || bytes.byteLength !== ref.byteLength) {
+				this.missing.set(ref.sha256, {
+					sha256: ref.sha256,
+					uri: ref.uri,
+					reason: `local bytes are ${digest} (${bytes.byteLength} bytes), not the ref's ${ref.sha256} (${ref.byteLength} bytes)`
+				});
+				continue;
+			}
+			const stored = await this.client.putSearchBlob(ref.sha256, new Uint8Array(bytes), ref.uri.endsWith(".json") ? "application/json" : "application/octet-stream", this.options.signal);
+			this.uploaded.add(ref.sha256);
+			this.counts.uploaded++;
+			this.counts[stored.state]++;
+		}
+	}
+};
+/** The longest prefix of `lines` within one request's limits. */
+function takeBatch(lines) {
+	const batch = [];
+	let bytes = 0;
+	for (const line of lines) {
+		const size = line.bytes - 1;
+		if (size > 1048576) throw new Error(`ledger line ${line.entry.sequence} holds ${size} bytes; one request carries at most ${SEARCH_LEDGER_BATCH_MAX_BYTES}`);
+		if (batch.length === 1e3 || bytes + size > 1048576) break;
+		batch.push(line);
+		bytes += size;
+	}
+	return batch;
+}
+/** Up to `limit` bytes of the file from `offset`; empty before the recorder
+* created the file. */
+async function readRange(path, offset, limit) {
+	let handle;
+	try {
+		handle = await open(path, "r");
+	} catch (error) {
+		if (error.code === "ENOENT" && offset === 0) return Buffer.alloc(0);
+		throw error;
+	}
+	try {
+		const { size } = await handle.stat();
+		if (size < offset) throw new Error(`${path} shrank below byte ${offset}`);
+		const bytes = Buffer.alloc(Math.min(limit, size - offset));
+		let read = 0;
+		while (read < bytes.byteLength) {
+			const { bytesRead } = await handle.read(bytes, read, bytes.byteLength - read, offset + read);
+			if (bytesRead === 0) break;
+			read += bytesRead;
+		}
+		return bytes.subarray(0, read);
+	} finally {
+		await handle.close();
+	}
+}
+/** The bytes at a `file:` ref, or why there are none. */
+async function readBlob(uri) {
+	if (!uri.startsWith("file:")) return `the shipper reads only file: refs, not ${uri.split(":")[0]}:`;
+	try {
+		return await readFile(fileURLToPath(uri));
+	} catch (error) {
+		return `unreadable: ${error.code ?? String(error)}`;
+	}
+}
+/**
+* Run a ship that must never fail its caller, such as the one a loop runs at
+* its end. A failure, a store short of the local ledger, or a blob that did
+* not upload is logged with the command that resumes it.
+*/
+async function shipBestEffort(ship, ledgerPath) {
+	const resume = `agent-eval search ship ${ledgerPath}`;
+	try {
+		const shipped = await ship();
+		if (shipped.head.nextSequence < shipped.localLines) console.warn(`[agent-eval] search ${shipped.searchId}: the store holds ${shipped.head.nextSequence} of ${shipped.localLines} ledger entries; resume with ${resume}`);
+		if (shipped.blobs.missing.length > 0) console.warn(`[agent-eval] search ${shipped.searchId}: ${shipped.blobs.missing.length} blob(s) were not uploaded, first: ${shipped.blobs.missing[0].reason}`);
+		return shipped;
+	} catch (error) {
+		console.warn(`[agent-eval] search ledger ship failed (continuing; resume with ${resume}): ${error instanceof Error ? error.message : String(error)}`);
+		return;
+	}
+}
+//#endregion
+export { TraceSpanEventSchema as C, IngestTracesRequestSchema as S, HOSTED_WIRE_VERSION as T, admitSearchLedgerBatch as _, HostedRequestError as a, searchLedgerHeadPath as b, hostedTenantFromEnv as c, SEARCH_LEDGER_BATCH_MAX_LINES as d, SEARCH_LEDGER_INGEST_PATH as f, SearchRunKindSchema as g, SearchLedgerHeadSchema as h, startSearchShipper as i, IngestSearchLedgerRequestSchema as l, SearchLedgerConflictSchema as m, shipBestEffort as n, createHostedClient as o, SearchBlobPutResponseSchema as p, shipSearchLedger as r, hostedClientFromEnv as s, SearchShipConflictError as t, SEARCH_LEDGER_BATCH_MAX_BYTES as u, searchBlobPath as v, UnixNanoTimestampSchema as w, IngestResponseSchema as x, searchLedgerArtifactRefs as y };
+
+//# sourceMappingURL=search-shipper-C55V7HE3.js.map