@hue-run/sdk 0.20.1 → 0.20.2

package/CLI.md

@@ -42,7 +42,7 @@ project manifest are refused because managers can update ancestor locks; Python
 The generated `hue.setup.mjs` or `hue_setup.py` always selects `captureContent: false` /
 `capture_content=False`. For a supported application, setup installs the dependency and adds the
 managed import and middleware registration to the existing entrypoint; an unreferenced helper is
-not a completed integration. TypeScript uses `@hue-run/sdk@0.20.1`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.20.2`, `@opentelemetry/api@1.9.1` and
 `@opentelemetry/context-async-hooks@2.11.0`; Python setup uses its separately tested package pin.
 Content capture requires an ordinary account-managed key and a later explicit application decision.
 
@@ -115,6 +115,8 @@ hue login                 # validate keys created in Hue and store them in ./.en
 hue mcp install --client claude-code # write the Hue MCP configuration for a coding agent
 hue listen --subscription <id> --forward-to http://localhost:3000/slack/events # deliver events to a local bot
 hue import langfuse --from 2026-01-01 --dry-run # count a Langfuse project's traces, then import them
+hue traces import prepare ./exports --out ./exports.hue-import --json # convert exports into a bundle
+hue traces import upload ./exports.hue-import --authorization-file ./authorization.json --json # deliver it
 ```
 
 Hosted setup accepts HTTPS origins only. HTTP is accepted solely for `localhost`, `127.0.0.1` and
@@ -379,8 +381,8 @@ and Hue never receives or stores them. The command is part of the `hue` executab
 #   LANGFUSE_PUBLIC_KEY=pk-lf-...
 #   LANGFUSE_SECRET_KEY=sk-lf-...
 #   LANGFUSE_BASE_URL=https://cloud.langfuse.com
-npx -y @hue-run/sdk@0.20.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` come from the environment or `--env-path`
@@ -491,6 +493,96 @@ once, abandoning exports still in flight for the next run to send. Exit codes: `
 trace was imported, `1` a trace, span or file was not (or a key was refused), `2` usage error, `130`
 stopped.
 
+## Import a bundle of existing traces
+
+`hue traces import` brings historical traces into Hue from exports you already hold: OTLP/JSON
+trace exports (a `{"resourceSpans": […]}` document, a list of them, or one per line), complete
+Langfuse observation exports (the `data` or native `observations` envelope) and text ATIF v1.7 and
+v1.8 exports, embedded subagents included. It needs no project key. `prepare` runs on the machine
+that holds the exports and sends nothing; a Hue MCP connection then authorizes the delivery
+(`prepare_trace_import`); `upload` delivers the bundle with that authorization, and
+`get_trace_import` reports what arrived.
+
+```sh
+npx -y @hue-run/sdk@latest traces import prepare ./exports --out ./exports.hue-import --json
+npx -y @hue-run/sdk@latest traces import upload ./exports.hue-import --authorization-file ./authorization.json --json
+```
+
+**Prepare.** `prepare <path>` reads a file, a directory tree or a ZIP archive (members are inflated
+in memory; encrypted members, unsafe paths and nested archives are listed, not read) and
+recognizes each file by its content, never by its name. Every trace becomes gzip OTLP/JSON batches
+of at most 3 MiB decoded and 900 KiB on the wire, written to `--out` (default `<path>.hue-import`,
+created with mode 0700) beside `manifest.json`, which declares each trace's id, span count, batches
+(by the SHA-256 of each gzip body), large values, history owner and origin. A text value over 1 MiB
+is stored as a value of its own and listed in `hue.blobs`, as the exporter lists the values it
+uploads. OTLP spans are kept as recorded; a trace or span id that is not an OpenTelemetry id (an
+exporter's UUID, for example) is mapped to one derived from it by SHA-256, with the original kept
+as `hue.import.original_trace_id` or `hue.import.original_span_id`. A Langfuse observation becomes
+one span keeping its whole record (`hue.import.source_record`) beside the `langfuse.*` and GenAI
+attributes Hue reads; an id that is no OpenTelemetry id is mapped as `hue import langfuse` maps it,
+so an export and a live import of the same trace agree. An ATIF export becomes one trace: an agent
+span for the run, a model span per agent step with the conversation so far, a tool span per call,
+each embedded subagent as its own agent span under the call that spawned it, and the export's
+`extra.user_id` as the trace's `user.id`. ATIF records instants, not durations, so model and tool
+spans are points in time, and a tool's result is kept as text with no error status of the
+importer's making. The same trace in two files is one trace when the copies agree and a refusal
+when they differ; a trace with more than 100,000 spans, 64 batches or 1,000 values is refused and
+named. Nothing about where a file sat or what it was called reaches a span: a renamed, reordered
+or re-zipped copy of the bundle prepares to byte-identical batches and the same manifest digest.
+
+The report (`--json` prints it as one object) names `manifest_digest`, `totals` (traces, batches,
+spans, blobs, bytes) and `source`, which `prepare_trace_import` takes as given; the formats
+recognized and the traces each file held; the files it could not read, with the reason; the traces
+and spans it refused; the traces without a history owner (a root `user.id`, a Langfuse `userId`, an
+ATIF `extra.user_id`, or an explicit `hue.world.entity.namespace` and `hue.world.entity.id`), which
+import like any other trace but leave a gap in continuous history; the origin each source recorded
+(`production`, `evaluation`, `simulation` or `unknown`; evaluation and simulation traffic is
+imported and kept out of production history); and the traces whose vendor ids were mapped. An
+existing `--out` directory is accepted only while it holds nothing but an earlier preparation and
+no upload has started in it.
+
+**Authorize.** Call `prepare_trace_import` over the Hue MCP with the report's `manifest_digest`,
+`totals` and `source`. It answers the import id, `upload_url` and an `authorization` (`hue_it_` and
+43 characters) valid for an hour. Save its answer, or the authorization alone, in a private file
+(mode 0600; never in a transcript, a message or a shell history). The same digest in the same
+project is the same import: calling again renews the authorization for an interrupted upload and
+revokes the earlier one.
+
+**Upload.** `upload <directory> --authorization-file <file>` reads the authorization from the file
+(its JSON answer, or the authorization on the first line and the `upload_url` on the second;
+`--import-url` names the URL otherwise, and `--origin` refuses a URL on any other Hue origin),
+never from the command line or the environment, and never prints it. It registers the manifest's
+exact bytes, then, trace by trace in declared order and two requests at a time, reserves each large
+value, sends it to the URL Hue answers and completes it, posts each batch with its SHA-256 in
+`Hue-Import-Batch`, and reads the trace's receipt for every span id: a trace counts as verified only
+when Hue confirms every span. It then reconciles and completes the import. Progress is written to
+`progress.json` in the bundle as it goes; running the same command again resumes there, and what
+Hue already holds is not sent twice (a batch sent again after a lost acknowledgement is taken as
+duplicates). Connection failures, timeouts, `408`, `429` and `5xx` answers are retried after 1, 2,
+4, 8, 16 and 30 seconds, waiting for `Retry-After`; after eight retries the command stops and the
+next run resumes. Ctrl+C or `SIGTERM` finishes the requests in flight, saves progress and exits
+`130`; a second signal stops at once.
+
+**What Hue refuses.** Every refusal carries a fixed code, which the report names in `error.code`.
+An expired or replaced authorization (`401`), a lapsed connection (`403` `authority_lapsed`) and an
+expired import (`410`) stop the upload: call `prepare_trace_import` again with the same
+`manifest_digest` and `totals`, write the new authorization to the file and run the same command.
+A manifest whose digest or totals are not the import's (`409`), an authorization of another import
+(`403`), an unknown import (`404`) and a canceled import (`410`) are final. A batch or value Hue
+refuses for the trace's own sake (undeclared, another digest, another trace's records, fewer
+finished spans than declared, a size or type the manifest did not declare), or a record Hue already
+holds under the same id with other content, is a conflict: it is recorded, the trace is reported,
+none of its later records are sent, and the same bytes are never sent again. An import Hue reports
+already completed is done: the command exits `0` and points to `get_trace_import`.
+
+**Output and exit codes.** Without `--json`, the command prints the registration, every hundredth
+verified trace, each conflict and a summary. With `--json`, one progress object per line goes to
+stderr and the report to stdout: the state (`completed`, `incomplete`, `stopped` or `failed`), the
+traces verified and conflicted, the batches landed and values stored, Hue's own note and the traces
+it still lists when completion was refused, the conflicts with their codes, and `next_action`. Exit
+codes: `0` prepared or completed, `1` not completed (the report says what to do next), `2` usage
+error, `130` stopped.
+
 ## Local state and conflicts
 
 Before its first network write, setup creates a lowercase UUIDv4 and a 32-byte random installation
@@ -595,7 +687,7 @@ node packages/sdk-typescript/scripts/verify-package.mjs --artifacts-dir .artifac
 # Set project to an existing supported fixture; use the same directory on resume.
 project=/absolute/path/to/supported-fixture
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.20.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.2.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -606,7 +698,7 @@ the private local handoff and finish the real browser claim, then reconcile the
 
 ```sh
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.20.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.20.2.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -648,10 +740,10 @@ otherwise. Never hand the agent Hue-native tools (`context.tools`, `context.mcp`
 production agent lacks. Pin the SDK, so the agent's repository gains no dependency:
 
 ```sh
-npx -y @hue-run/sdk@0.20.1 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.20.1 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
-npx -y @hue-run/sdk@0.20.1 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.20.1 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.20.2 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.20.2 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
+npx -y @hue-run/sdk@0.20.2 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.20.2 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
 ```
 
 One invocation creates one run holding every selected case; it prints the run URL
@@ -689,7 +781,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.20.1 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.20.2 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.

package/ENVIRONMENTS.md

@@ -332,7 +332,7 @@ A refusal such as 409 `simulation_gateway_required` exposes its validated server
 
 `agentEnvironment` removes Hue control-plane credentials from the child by default: `HUE_API_KEY`,
 `HUE_MCP_KEY`, and any value carrying a Hue control-plane credential (`hue_sk_`, `hue_setup_`,
-`hue_attempt_`, `hue_mcp_`, `hue_inv_`, `hue_install_`, `hue_at_`, `hue_rt_`, `hue_oauth_`)
+`hue_attempt_`, `hue_mcp_`, `hue_inv_`, `hue_install_`, `hue_at_`, `hue_rt_`, `hue_it_`, `hue_oauth_`)
 anywhere in it, including wrapped, percent-encoded or JSON-Unicode-escaped values. World tokens and
 `hue_sim_` capabilities pass. Pass `includeHueCredentials: true` only for an agent that must call
 Hue's own API.

package/README.md

@@ -536,8 +536,8 @@ the Langfuse project's own keys (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, a
 `HUE_API_KEY`:
 
 ```sh
-npx -y @hue-run/sdk@0.20.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.20.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.20.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.20.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 - It reads Langfuse Cloud and self-hosted v4 through the Observations API v2, and self-hosted v3
@@ -558,6 +558,34 @@ The command has no Python counterpart; it runs with `npx` for an application in
 [Import traces from Langfuse](CLI.md#import-traces-from-langfuse) for every option, the attribute
 mapping, media handling, limits and exit codes.
 
+## Import a bundle of existing traces
+
+`hue traces import` brings exports you already hold into Hue in two steps, with no project key.
+`prepare` converts the bundle on your machine and sends nothing; a Hue MCP connection authorizes
+the delivery with `prepare_trace_import`; `upload` delivers it with that authorization. Sources
+are files, directories or ZIP archives of OTLP/JSON trace exports, complete Langfuse observation
+exports and text ATIF v1.7 and v1.8 exports, recognized by content:
+
+```sh
+npx -y @hue-run/sdk@latest traces import prepare ./exports --out ./exports.hue-import --json
+# Call prepare_trace_import with the report's manifest_digest, totals and source, and save its
+# answer (or the authorization alone) in a private file.
+npx -y @hue-run/sdk@latest traces import upload ./exports.hue-import --authorization-file ./authorization.json --json
+```
+
+- `prepare` writes each trace as gzip OTLP/JSON batches beside a manifest and reports the
+  manifest's digest and totals, the formats recognized, the files it could not read, invalid vendor
+  ids it mapped to OpenTelemetry ids, and the traces without a history owner (a root `user.id` or an
+  explicit entity). Nothing about a file's name or place reaches a span.
+- `upload` registers the manifest, sends each trace's large values and batches in order, two
+  requests at a time, checks every span's receipt, reconciles and completes the import. Interrupted,
+  run it again: it resumes from `progress.json` in the bundle. An expired authorization is renewed
+  by calling `prepare_trace_import` again with the same digest and totals.
+- The authorization (`hue_it_…`) is read only from the file and never printed.
+
+See [Import a bundle of existing traces](CLI.md#import-a-bundle-of-existing-traces) for the
+formats, the report, what Hue refuses and the exit codes.
+
 ## Vercel AI SDK 6
 
 AI SDK 6 accepts a per-call tracer through `experimental_telemetry`. Pass

package/dist/cli/traces-import-convert.d.ts

@@ -0,0 +1,262 @@
+/**
+ * The conversions behind `hue traces import prepare`: a source file is recognized by its content
+ * (an OTLP/JSON trace export, a complete Langfuse observation export or a text ATIF export),
+ * each trace becomes OTLP/JSON entries, one span each, that keep the recorded ids, hierarchy,
+ * timestamps, content, errors and usage, and the entries are packed into deterministic gzip
+ * batches. Nothing here depends on where a file sat or what it was called: a renamed or repacked
+ * bundle converts to byte-identical batches, so the manifest's digests name the same import.
+ */
+export declare const traceImportFormats: readonly ["otlp_json", "langfuse_observations", "atif"];
+export type TraceImportFormat = (typeof traceImportFormats)[number];
+export declare const traceImportOrigins: readonly ["production", "evaluation", "simulation", "unknown"];
+export type TraceImportOrigin = (typeof traceImportOrigins)[number];
+/** The bounds the import routes hold a manifest to. */
+export declare const traceImportLimits: {
+    readonly traces: 10000;
+    readonly batchesPerTrace: 64;
+    readonly blobsPerTrace: 1000;
+    readonly spansPerTrace: 100000;
+    readonly manifestBytes: number;
+    readonly batchBytes: number;
+    readonly blobBytes: 1000000000;
+};
+/** One batch, decoded, and on the wire: well inside the receiver's request bounds. */
+export declare const MAX_BATCH_DECODED_BYTES: number;
+export declare const MAX_BATCH_WIRE_BYTES: number;
+/** The largest value a record keeps inline; a longer text is stored apart from its span. */
+export declare const MAX_INLINE_VALUE_BYTES: number;
+export declare const SOURCE_RECORD = "hue.import.source_record";
+export declare const SOURCE_ENVELOPE = "hue.import.source_envelope";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface OtlpValue {
+    stringValue?: string;
+    boolValue?: boolean;
+    intValue?: string;
+    doubleValue?: number;
+    arrayValue?: {
+        values: OtlpValue[];
+    };
+    kvlistValue?: {
+        values: OtlpAttribute[];
+    };
+    bytesValue?: string;
+}
+export interface OtlpAttribute {
+    key: string;
+    value: OtlpValue;
+}
+export type ImportSpan = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpAttribute[];
+    status: {
+        code: number;
+        message?: string;
+    };
+};
+/** One resource group holding one scope group holding one span: the unit the packer serializes.
+ * A converted span is an {@link ImportSpan}; an OTLP/JSON span is kept as recorded. */
+export interface ImportEntry {
+    [key: string]: unknown;
+    scopeSpans: {
+        [key: string]: unknown;
+        spans: Record<string, unknown>[];
+    }[];
+}
+export interface TraceIdentity {
+    user?: string;
+    entity?: {
+        namespace: string;
+        id: string;
+    };
+    session?: string;
+}
+export interface PreparedBlob {
+    sha256: string;
+    byteSize: number;
+    contentType: string;
+    bytes: Uint8Array;
+}
+export interface ConvertedTrace {
+    traceId: string;
+    format: TraceImportFormat;
+    entries: ImportEntry[];
+    blobs: PreparedBlob[];
+    identity?: TraceIdentity;
+    origin: TraceImportOrigin;
+    /** The SHA-256 of every source file that held part of the trace. */
+    sourceDigests: Set<string>;
+    remappedTraceId: boolean;
+    remappedSpans: number;
+}
+/** A trace, span or file that was not converted, and why. */
+export interface Refusal {
+    traceId?: string;
+    reason: string;
+}
+export declare class ConversionError extends Error {
+}
+export declare const sha256Hex: (value: string | Uint8Array) => string;
+/**
+ * JSON text parsed with every integer too large for a JavaScript number kept as its decimal
+ * text, so an OTLP timestamp written as a number keeps its nanoseconds. `unsafeIntegers` says
+ * whether any was found; the Langfuse and ATIF readers refuse such a file, as Hue's do.
+ */
+export declare function parseJsonText(text: string): {
+    value: unknown;
+    unsafeIntegers: boolean;
+};
+/** Refuses a source value that JavaScript or OTLP cannot retain exactly; never omits it. */
+export declare function validateSource(value: JsonValue, depth?: number): void;
+/** JSON.parse otherwise loses duplicate members and can round decimal argument values. */
+export declare function validateJsonText(raw: string): void;
+export type DetectedSource = {
+    format: "otlp_json";
+    envelopes: Record<string, unknown>[];
+} | {
+    format: "langfuse_observations";
+    observations: Record<string, JsonValue>[];
+    envelope: Record<string, JsonValue>;
+    unsafeIntegers: boolean;
+} | {
+    format: "atif";
+    text: string;
+    document: unknown;
+    unsafeIntegers: boolean;
+} | {
+    format: "unsupported";
+    reason: string;
+};
+/** What a file holds, read from its content alone; never from its name. */
+export declare function detectFormat(bytes: Uint8Array): DetectedSource;
+export declare function anyValue(value: JsonValue): OtlpValue;
+/** The large values one trace stores apart from its spans, each once by digest. */
+export declare class BlobSink {
+    readonly blobs: Map<string, PreparedBlob>;
+    /** Stores a text whole and returns what its record keeps: the first 16 KiB and the `hue.blobs`
+     * entry; undefined when the text is over the limit of one stored value. */
+    place(key: string, text: string): {
+        prefix: string;
+        entry: string;
+    } | undefined;
+    /** The values in digest order: the manifest lists a trace's values the same whatever order its
+     * sources were read in, so renaming or repacking them keeps the manifest digest. */
+    sorted(): PreparedBlob[];
+}
+/** A converted span's attributes: a value over the inline limit is stored apart from the span
+ * through the trace's {@link BlobSink} and listed in `hue.blobs`, as the SDK's exporter lists
+ * the values it uploads, with the key in `hue.truncated`. */
+export declare class AttributeList {
+    private readonly blobs;
+    readonly values: OtlpAttribute[];
+    private readonly listed;
+    private readonly truncated;
+    constructor(blobs: BlobSink);
+    add(key: string, value: JsonValue): void;
+    json(key: string, value: unknown): void;
+    finish(): OtlpAttribute[];
+}
+/** Gathers the spans of OTLP/JSON exports by trace, across files: an export writes a trace's
+ * spans in the requests that carried them, which need not be one file. */
+export declare class OtlpTraceCollector {
+    private readonly traces;
+    /** Adds every span of the envelopes; the spans refused, with their reasons. */
+    add(envelopes: readonly Record<string, unknown>[], sourceDigest: string): Refusal[];
+    private addSpan;
+    /** Every trace gathered so far, spans in time order, and the traces refused whole. */
+    finish(): {
+        traces: ConvertedTrace[];
+        refused: Refusal[];
+    };
+}
+export declare function unixNano(value: JsonValue | undefined): string;
+/** Gathers Langfuse observations by trace across files and converts each trace as Hue's reader
+ * converts an observation export: one span per observation, the record kept whole. */
+export declare class LangfuseTraceCollector {
+    private readonly traces;
+    add(observations: readonly Record<string, JsonValue>[], envelope: Record<string, JsonValue>, sourceDigest: string): void;
+    finish(): {
+        traces: ConvertedTrace[];
+        refused: Refusal[];
+    };
+}
+/** The ATIF reader's bounds: a text export of at most 4 MiB and 2,000 spans. */
+export declare const MAX_ATIF_FILE_BYTES: number;
+export declare const MAX_ATIF_SPANS = 2000;
+/** Retains nanoseconds and requires an explicit timezone, valid calendar date and OTLP uint64. */
+export declare function atifUnixNano(value: string): string;
+/**
+ * A text ATIF v1.7 or v1.8 export as one trace: an agent span for the run, a model span per
+ * agent step with the conversation so far, a tool span per call under it, and an embedded
+ * subagent trajectory as its own agent span under the tool span of the call that spawned it.
+ * Identity is run scoped (`session_id` and `trajectory_id`), never a path. The complete original
+ * document stays on the root; each model and tool span keeps its own record. ATIF supplies step
+ * instants, not call durations: model and tool spans are zero-duration point spans.
+ */
+export declare function convertAtifExport(source: Extract<DetectedSource, {
+    format: "atif";
+}>, rawBytes: number): ConvertedTrace;
+export interface PreparedBatch {
+    sha256: string;
+    body: Uint8Array;
+    decodedBytes: number;
+    spanIds: string[];
+}
+/** `Math.floor(numerator / divisor)` for safe nonnegative integers, without a division: the
+ * published package's import-boundary check reads a `/` after a name as a regular expression, so
+ * the quotient is estimated from the reciprocal and corrected by whole steps, which makes it
+ * exact on every engine. */
+export declare function integerQuotient(numerator: number, divisor: number): number;
+/**
+ * The trace's entries packed into gzip OTLP/JSON batches in order, each at most 3 MiB decoded
+ * and 900 KiB on the wire. Packing is linear and the output depends on the entries alone, so the
+ * same trace packs to the same batches whatever bundle it came from.
+ */
+export declare function batchEntries(entries: readonly ImportEntry[]): PreparedBatch[];
+export interface ManifestTrace {
+    trace_id: string;
+    span_count: number;
+    batches: {
+        sha256: string;
+        bytes: number;
+        span_count: number;
+    }[];
+    blobs: {
+        sha256: string;
+        byte_size: number;
+        content_type: string;
+    }[];
+    identity?: TraceIdentity;
+    origin: TraceImportOrigin;
+    source_digest?: string;
+}
+export interface TraceImportManifest {
+    version: 1;
+    source: {
+        formats: TraceImportFormat[];
+        helper: string;
+        helper_version?: string;
+    };
+    traces: ManifestTrace[];
+}
+export interface TraceImportTotals {
+    traces: number;
+    batches: number;
+    spans: number;
+    blobs: number;
+    bytes: number;
+}
+/** The totals a manifest adds up to, as Hue computes them. */
+export declare function manifestTotals(manifest: TraceImportManifest): TraceImportTotals;
+export declare function manifestTraceHasIdentity(trace: Pick<ManifestTrace, "identity">): boolean;
+/** A manifest's problem, or undefined: the shape and cross-checks Hue's registration applies
+ * (every trace id once, every batch digest once, each trace's batches adding up to its span
+ * count, each trace's values distinct) so a bundle is refused here, before any upload. */
+export declare function validateManifest(value: unknown): string | undefined;