@plune-ai/cli 0.6.0 → 0.7.0

package/dist/reporter-core.d.cts

@@ -0,0 +1,315 @@
+/**
+ * The platform's wire, mirrored in types — and only in types.
+ *
+ * There is deliberately no zod here. ADR 0012 says the platform owns the contract and clients
+ * conform to it; a second copy of the schema on the client is a second place to drift, and it
+ * would put a validation library into the dependency tree of every project that installs an
+ * adapter. The platform validates and answers with a named reason (`validation failed — <field>:
+ * <why>`), and that reason is what the reporter shows.
+ *
+ * What keeps these shapes honest is not a runtime check here but the platform's contract test
+ * against the published package — the same mechanism `cli-sync-contract.test.ts` already
+ * establishes for `plune sync`.
+ */
+/** Kinds of run the platform accepts. `mixed` is declared, never derived — "some of these were run
+ * by a person" is a fact about the process, not something visible in the results. */
+type RunKind = 'automated' | 'manual' | 'mixed' | 'eval';
+/** What a result finally means. The reporter never picks one of these — see `PendingResult`. */
+type ResultStatus = 'passed' | 'failed' | 'broken' | 'blocked' | 'skipped';
+/**
+ * The namespaces other tools already use for the same test.
+ *
+ * The ORDER is the platform's, and it matters there, not here: a lookup that names no kind
+ * resolves in that sequence. A client that reproduced the ranking would be a second place to
+ * forget it, so this list is only a vocabulary — the ranking stays server-side.
+ */
+type ExternalKeyKind = 'playwright-id' | 'path-title' | 'allure-history' | 'cairn-stable' | 'eval-id' | 'qase' | 'testrail';
+/** One candidate identifier for a test. `kind` omitted means "resolve it however you rank them". */
+interface KeyRef {
+    kind?: ExternalKeyKind;
+    value: string;
+}
+/** Where the run came from. Every field optional because a shard genuinely may not know it. */
+interface RunMeta {
+    sha?: string;
+    branch?: string;
+    ciUrl?: string;
+    runner?: string;
+}
+/** How the run itself went, as the runner measured it. `retry` 0 is the first attempt. */
+interface Execution {
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    retry: number;
+    worker?: string;
+}
+/** A link, not a file. Uploading artefacts is C3; this carries what someone else already hosts. */
+interface Attachment {
+    name: string;
+    url: string;
+    contentType?: string;
+}
+/** One assertion's outcome, in the shape the platform already stores for its own runner. */
+interface AssertionRecord {
+    type: string;
+    passed: boolean;
+    score?: number;
+    reason?: string;
+}
+/**
+ * One result, as an adapter hands it over — before it has a test case.
+ *
+ * `keys` rather than a `testCaseId` is the seam that keeps adapters thin AND leaves room for C2:
+ * an adapter says "here is how this test identifies itself", and resolving that to a case is the
+ * core's business. C2 adds rungs to the ladder by putting more candidates in this array; neither
+ * this shape nor the adapters change.
+ *
+ * `rawStatus` rather than `status` is the other half of that discipline. The platform maps a
+ * runner's word to a meaning per project (`timedOut` → `broken` by default, overridable), so a
+ * team can change what a timeout means to them without waiting for a reporter release. A reporter
+ * that decided the status would take that away and put two different answers on two surfaces.
+ */
+interface PendingResult {
+    resultKey: string;
+    /**
+     * The case this result IS, when the test says so outright — a `PluneId` annotation, or the
+     * `@P<id>` token C2 also reads out of a title.
+     *
+     * Separate from `keys` because it is a different claim, and the platform draws the same line:
+     * `plune-id` is deliberately absent from its external-key kinds, since it is the thing external
+     * keys resolve TO. Present means no lookup is needed for this result at all.
+     */
+    testCaseId?: string;
+    keys: KeyRef[];
+    /** Which runner produced this — the key into the project's status map. */
+    source: string;
+    /** The runner's own word: `passed`, `failed`, `timedOut`, `interrupted`, `skipped`. */
+    rawStatus: string;
+    /** What the author expected — `test.fail()` and friends. Absent means a pass was expected. */
+    expectedStatus?: ResultStatus;
+    execution?: Execution;
+    errorContext?: string;
+    params?: Record<string, unknown>;
+    attachments?: Attachment[];
+    assertions?: AssertionRecord[];
+}
+/** What a run submission looks like once a key has resolved. Built by the core, never by a caller. */
+interface ResultSubmission extends Omit<PendingResult, 'keys' | 'testCaseId'> {
+    testCaseId: string;
+}
+/** One entry of the "what this run intended to execute" list, from which the platform derives
+ * `notRun`. Either side may be given; the core fills `externalKey` from the adapter's key list. */
+interface ExpectedEntry {
+    testCaseId?: string;
+    externalKey?: KeyRef;
+}
+/** The run as the platform answers with it. Only `id` is load-bearing for the client. */
+interface RunRecord {
+    id: string;
+    projectId?: string;
+    schemaVersion?: number;
+}
+/** Per-element verdicts from a batch. `conflict` means two runners disagreed about one result —
+ * the platform refuses to resolve that by overwriting, and neither do we. */
+interface SubmitCounts {
+    accepted: number;
+    duplicate: number;
+    conflict: number;
+    rejected: number;
+}
+/** What the session accumulated, for the one summary line a reporter prints. */
+interface RunStats extends SubmitCounts {
+    /** Results whose keys matched no case — never sent, because inventing an id would write into
+     * somebody else's history. What to do about them is C2's ladder. */
+    unresolved: number;
+    /** Results written to the fallback file instead of the platform. */
+    deferred: number;
+}
+/** Everything the core needs to talk to a deployment. */
+interface ReporterConfig {
+    /** Base URL. Falls back to `PLUNE_API_URL`, then beta — the same resolution `sync` uses. */
+    apiUrl?: string;
+    /** Bearer token. Falls back to the store `plune login` writes. */
+    token?: string;
+    /** The key several shards share so they land in one run. Absent means a run of its own. */
+    externalKey?: string;
+    kind?: RunKind;
+    meta?: RunMeta;
+    /** Results per request. The platform's ceiling is 500. */
+    batchSize?: number;
+    /** Where unsent batches go. Defaults beside the run file the CLI already writes. */
+    fallbackPath?: string;
+    /** Transport seam — the same one `sync.ts` uses so tests need no server. */
+    fetchImpl?: typeof fetch;
+    /** Where a line for the operator goes. Defaults to stderr. */
+    log?: (line: string) => void;
+}
+
+/**
+ * A run in progress.
+ *
+ * `runId: null` is not an error state to check for — it is a run that never reached the platform,
+ * and everything below keeps working: results go to the fallback file, `finish` does nothing, and
+ * the test run itself is untouched. A reporter that failed a build because a dashboard was down
+ * would be worse than no reporter.
+ */
+interface RunSession {
+    readonly runId: string | null;
+    readonly joined: boolean;
+    readonly stats: Readonly<RunStats>;
+    /** Hand over one result. Sends a batch as soon as enough have accumulated. */
+    add(result: PendingResult): Promise<void>;
+    /** Send whatever is buffered. Safe to call when nothing is. */
+    flush(): Promise<void>;
+    /** Send what is left and close the run. */
+    finish(reason?: string): Promise<void>;
+    /** Send what is left and deliberately leave the run open — the shard case (AC-03). */
+    leaveOpen(): Promise<void>;
+}
+/**
+ * Start a run, or join the one that already carries this key.
+ *
+ * `expected` — one list of candidate identifiers per test the runner knows about — is used twice
+ * on purpose. It becomes `configuration.expected`, from which the platform derives what never ran
+ * (AC-09); and it is the input to the single up-front resolve, so the per-test path afterwards is
+ * a map lookup rather than a request (AC-10). A runner that cannot enumerate its tests passes
+ * nothing and resolves lazily on the first flush — same function, later moment.
+ */
+declare function startRun(passed: ReporterConfig, expected?: readonly (readonly KeyRef[])[]): Promise<RunSession>;
+
+/**
+ * The ceiling the platform's contract puts on `resultKey` (`resultSubmissionSchema`).
+ *
+ * Exported so the test asserts against the same number the fallback branch is chosen by, rather
+ * than against a copy of it.
+ */
+declare const RESULT_KEY_MAX = 200;
+/**
+ * The reporter's own id for one result — minted by the client, never by the server.
+ *
+ * It has to be **the same string** the second time the same result is reported, because that is
+ * the entire mechanism behind AC-04: `playwright merge-reports` runs the reporter again over the
+ * merged blob, and the platform's unique index on `(run_id, result_key)` answers `duplicate`
+ * instead of writing a second row. A key derived from anything that varies between the two passes
+ * — a timestamp, a counter, a random id — would double every result silently.
+ *
+ * Readable while it fits: this string lands in the database and in error messages, and
+ * `a1b2c3…#0` tells a person nothing about which test broke. Only when the plain form would
+ * exceed what the contract accepts does it fall back to a digest — and the digest covers the test
+ * id alone, so the retry stays visible and a flaky test's three attempts never collapse into one.
+ */
+declare function resultKey(testId: string, retry: number): string;
+
+/**
+ * What a CI job can tell the reporter without editing a config file.
+ *
+ * A Playwright config is committed; a CI job is not. Everything here exists so a pipeline can set
+ * the shared run key, the token and the batch size per job — the things that differ between the
+ * laptop the config was written on and the runner it executes on.
+ */
+/**
+ * Names the reporter promises but the platform cannot yet store (feature D13).
+ *
+ * They are listed rather than ignored because of how they would fail otherwise: a run's `meta`
+ * strips keys it does not know, so sending `PLUNE_ENV` there would be accepted, dropped, and look
+ * exactly like success. A client believing it saved something the server discarded is the most
+ * expensive kind of quiet — cheaper to say "not yet" out loud.
+ */
+declare const UNSUPPORTED_VARS: readonly ["PLUNE_RUN_TITLE", "PLUNE_ENV", "PLUNE_LABELS", "PLUNE_GROUP"];
+interface EnvSettings {
+    /** Config fields the environment supplied. Anything passed explicitly outranks these. */
+    config: Partial<ReporterConfig>;
+    /** This process must not close the run — several share it, or the job closes it itself. */
+    keepOpen: boolean;
+    /** Variables that were set and have nowhere to land. The caller says so once. */
+    ignored: string[];
+}
+declare function readEnv(env?: NodeJS.ProcessEnv): EnvSettings;
+
+/**
+ * What ends up in a deferred batch.
+ *
+ * Two shapes, because two things can fail. A batch refused by the platform is already resolved
+ * (`ResultSubmission`), and replay sends it as it is. A batch deferred because the platform was
+ * never reached has not been resolved at all (`PendingResult`), and replay has to look its keys
+ * up first. Flattening them into one shape would mean inventing a `testCaseId` for the second
+ * case, which is exactly what AC-11 forbids.
+ */
+type DeferredResult = ResultSubmission | PendingResult;
+/** Beside `last-run.json`, because that is where a Plune user already looks for a run. */
+declare const DEFAULT_FALLBACK_PATH: string;
+/**
+ * One batch that could not be sent.
+ *
+ * A batch rather than a result: the batch is the unit that failed, and it is the unit `plune run
+ * report` will re-send unchanged. Splitting it into results here would mean re-grouping them there
+ * against a size the platform may have changed in the meantime.
+ *
+ * `runId: null` is a real state, not a missing value — the platform was unreachable when the run
+ * was supposed to be created, so these results have no run yet and replay has to make one.
+ */
+interface DeferredBatch {
+    runId: string | null;
+    externalKey: string | null;
+    results: DeferredResult[];
+}
+/**
+ * Append a batch to the fallback file, creating its directory if nobody has yet.
+ *
+ * JSONL and synchronous, both for the same reason: a run is being abandoned when this is called,
+ * and the next thing to happen may be the process dying. A line that is already flushed stays
+ * readable no matter what happens to the ones after it, which one large JSON document rewritten
+ * on every batch would not.
+ *
+ * Nothing about the connection goes in — not the token, not the headers, not the config. The line
+ * holds who the run was and what did not reach it, which is exactly what replaying needs.
+ */
+declare function appendBatch(file: string, batch: DeferredBatch): void;
+
+/**
+ * The only thing in this package that talks to the platform.
+ *
+ * It classifies rather than throws. Every caller has to decide something different about a
+ * failure — a batch goes to the fallback file, a rejected token silences the rest of the run, a
+ * closed run is a configuration mistake worth naming — and an exception hierarchy would make each
+ * of those a `catch` that re-derives what already happened here.
+ *
+ * It also does not log. Anything printed about a failure is printed by the session, which knows
+ * the context; keeping the token's only home in this file is what makes AC-12 structural rather
+ * than a rule someone has to remember.
+ */
+type ClientFailureKind = 
+/** The token was refused. Retrying sends the same token to the same door. */
+'auth'
+/** The server understood and said no: a closed run, an impossible lifecycle transition. */
+ | 'conflict'
+/** The body was refused. It will be refused identically next time. */
+ | 'invalid'
+/** Nobody answered, or answered with their own failure. Worth another try. */
+ | 'unavailable'
+/** Everything else — reported, never retried, because we cannot say retrying would help. */
+ | 'other';
+type ClientOutcome<T> = {
+    ok: true;
+    status: number;
+    body: T;
+} | {
+    ok: false;
+    kind: ClientFailureKind;
+    status: number | null;
+    detail: string;
+};
+interface ClientOptions {
+    apiUrl: string;
+    token: string;
+    fetchImpl?: typeof fetch;
+    /** Test seam — the same idea as `fetchImpl`, so a retry test costs milliseconds, not seconds. */
+    wait?: (ms: number) => Promise<void>;
+}
+interface PlatformClient {
+    post<T>(path: string, body: unknown): Promise<ClientOutcome<T>>;
+}
+declare function createClient(opts: ClientOptions): PlatformClient;
+
+export { type AssertionRecord, type Attachment, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type SubmitCounts, UNSUPPORTED_VARS, appendBatch, createClient, readEnv, resultKey, startRun };

package/dist/reporter-core.d.ts

@@ -0,0 +1,315 @@
+/**
+ * The platform's wire, mirrored in types — and only in types.
+ *
+ * There is deliberately no zod here. ADR 0012 says the platform owns the contract and clients
+ * conform to it; a second copy of the schema on the client is a second place to drift, and it
+ * would put a validation library into the dependency tree of every project that installs an
+ * adapter. The platform validates and answers with a named reason (`validation failed — <field>:
+ * <why>`), and that reason is what the reporter shows.
+ *
+ * What keeps these shapes honest is not a runtime check here but the platform's contract test
+ * against the published package — the same mechanism `cli-sync-contract.test.ts` already
+ * establishes for `plune sync`.
+ */
+/** Kinds of run the platform accepts. `mixed` is declared, never derived — "some of these were run
+ * by a person" is a fact about the process, not something visible in the results. */
+type RunKind = 'automated' | 'manual' | 'mixed' | 'eval';
+/** What a result finally means. The reporter never picks one of these — see `PendingResult`. */
+type ResultStatus = 'passed' | 'failed' | 'broken' | 'blocked' | 'skipped';
+/**
+ * The namespaces other tools already use for the same test.
+ *
+ * The ORDER is the platform's, and it matters there, not here: a lookup that names no kind
+ * resolves in that sequence. A client that reproduced the ranking would be a second place to
+ * forget it, so this list is only a vocabulary — the ranking stays server-side.
+ */
+type ExternalKeyKind = 'playwright-id' | 'path-title' | 'allure-history' | 'cairn-stable' | 'eval-id' | 'qase' | 'testrail';
+/** One candidate identifier for a test. `kind` omitted means "resolve it however you rank them". */
+interface KeyRef {
+    kind?: ExternalKeyKind;
+    value: string;
+}
+/** Where the run came from. Every field optional because a shard genuinely may not know it. */
+interface RunMeta {
+    sha?: string;
+    branch?: string;
+    ciUrl?: string;
+    runner?: string;
+}
+/** How the run itself went, as the runner measured it. `retry` 0 is the first attempt. */
+interface Execution {
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    retry: number;
+    worker?: string;
+}
+/** A link, not a file. Uploading artefacts is C3; this carries what someone else already hosts. */
+interface Attachment {
+    name: string;
+    url: string;
+    contentType?: string;
+}
+/** One assertion's outcome, in the shape the platform already stores for its own runner. */
+interface AssertionRecord {
+    type: string;
+    passed: boolean;
+    score?: number;
+    reason?: string;
+}
+/**
+ * One result, as an adapter hands it over — before it has a test case.
+ *
+ * `keys` rather than a `testCaseId` is the seam that keeps adapters thin AND leaves room for C2:
+ * an adapter says "here is how this test identifies itself", and resolving that to a case is the
+ * core's business. C2 adds rungs to the ladder by putting more candidates in this array; neither
+ * this shape nor the adapters change.
+ *
+ * `rawStatus` rather than `status` is the other half of that discipline. The platform maps a
+ * runner's word to a meaning per project (`timedOut` → `broken` by default, overridable), so a
+ * team can change what a timeout means to them without waiting for a reporter release. A reporter
+ * that decided the status would take that away and put two different answers on two surfaces.
+ */
+interface PendingResult {
+    resultKey: string;
+    /**
+     * The case this result IS, when the test says so outright — a `PluneId` annotation, or the
+     * `@P<id>` token C2 also reads out of a title.
+     *
+     * Separate from `keys` because it is a different claim, and the platform draws the same line:
+     * `plune-id` is deliberately absent from its external-key kinds, since it is the thing external
+     * keys resolve TO. Present means no lookup is needed for this result at all.
+     */
+    testCaseId?: string;
+    keys: KeyRef[];
+    /** Which runner produced this — the key into the project's status map. */
+    source: string;
+    /** The runner's own word: `passed`, `failed`, `timedOut`, `interrupted`, `skipped`. */
+    rawStatus: string;
+    /** What the author expected — `test.fail()` and friends. Absent means a pass was expected. */
+    expectedStatus?: ResultStatus;
+    execution?: Execution;
+    errorContext?: string;
+    params?: Record<string, unknown>;
+    attachments?: Attachment[];
+    assertions?: AssertionRecord[];
+}
+/** What a run submission looks like once a key has resolved. Built by the core, never by a caller. */
+interface ResultSubmission extends Omit<PendingResult, 'keys' | 'testCaseId'> {
+    testCaseId: string;
+}
+/** One entry of the "what this run intended to execute" list, from which the platform derives
+ * `notRun`. Either side may be given; the core fills `externalKey` from the adapter's key list. */
+interface ExpectedEntry {
+    testCaseId?: string;
+    externalKey?: KeyRef;
+}
+/** The run as the platform answers with it. Only `id` is load-bearing for the client. */
+interface RunRecord {
+    id: string;
+    projectId?: string;
+    schemaVersion?: number;
+}
+/** Per-element verdicts from a batch. `conflict` means two runners disagreed about one result —
+ * the platform refuses to resolve that by overwriting, and neither do we. */
+interface SubmitCounts {
+    accepted: number;
+    duplicate: number;
+    conflict: number;
+    rejected: number;
+}
+/** What the session accumulated, for the one summary line a reporter prints. */
+interface RunStats extends SubmitCounts {
+    /** Results whose keys matched no case — never sent, because inventing an id would write into
+     * somebody else's history. What to do about them is C2's ladder. */
+    unresolved: number;
+    /** Results written to the fallback file instead of the platform. */
+    deferred: number;
+}
+/** Everything the core needs to talk to a deployment. */
+interface ReporterConfig {
+    /** Base URL. Falls back to `PLUNE_API_URL`, then beta — the same resolution `sync` uses. */
+    apiUrl?: string;
+    /** Bearer token. Falls back to the store `plune login` writes. */
+    token?: string;
+    /** The key several shards share so they land in one run. Absent means a run of its own. */
+    externalKey?: string;
+    kind?: RunKind;
+    meta?: RunMeta;
+    /** Results per request. The platform's ceiling is 500. */
+    batchSize?: number;
+    /** Where unsent batches go. Defaults beside the run file the CLI already writes. */
+    fallbackPath?: string;
+    /** Transport seam — the same one `sync.ts` uses so tests need no server. */
+    fetchImpl?: typeof fetch;
+    /** Where a line for the operator goes. Defaults to stderr. */
+    log?: (line: string) => void;
+}
+
+/**
+ * A run in progress.
+ *
+ * `runId: null` is not an error state to check for — it is a run that never reached the platform,
+ * and everything below keeps working: results go to the fallback file, `finish` does nothing, and
+ * the test run itself is untouched. A reporter that failed a build because a dashboard was down
+ * would be worse than no reporter.
+ */
+interface RunSession {
+    readonly runId: string | null;
+    readonly joined: boolean;
+    readonly stats: Readonly<RunStats>;
+    /** Hand over one result. Sends a batch as soon as enough have accumulated. */
+    add(result: PendingResult): Promise<void>;
+    /** Send whatever is buffered. Safe to call when nothing is. */
+    flush(): Promise<void>;
+    /** Send what is left and close the run. */
+    finish(reason?: string): Promise<void>;
+    /** Send what is left and deliberately leave the run open — the shard case (AC-03). */
+    leaveOpen(): Promise<void>;
+}
+/**
+ * Start a run, or join the one that already carries this key.
+ *
+ * `expected` — one list of candidate identifiers per test the runner knows about — is used twice
+ * on purpose. It becomes `configuration.expected`, from which the platform derives what never ran
+ * (AC-09); and it is the input to the single up-front resolve, so the per-test path afterwards is
+ * a map lookup rather than a request (AC-10). A runner that cannot enumerate its tests passes
+ * nothing and resolves lazily on the first flush — same function, later moment.
+ */
+declare function startRun(passed: ReporterConfig, expected?: readonly (readonly KeyRef[])[]): Promise<RunSession>;
+
+/**
+ * The ceiling the platform's contract puts on `resultKey` (`resultSubmissionSchema`).
+ *
+ * Exported so the test asserts against the same number the fallback branch is chosen by, rather
+ * than against a copy of it.
+ */
+declare const RESULT_KEY_MAX = 200;
+/**
+ * The reporter's own id for one result — minted by the client, never by the server.
+ *
+ * It has to be **the same string** the second time the same result is reported, because that is
+ * the entire mechanism behind AC-04: `playwright merge-reports` runs the reporter again over the
+ * merged blob, and the platform's unique index on `(run_id, result_key)` answers `duplicate`
+ * instead of writing a second row. A key derived from anything that varies between the two passes
+ * — a timestamp, a counter, a random id — would double every result silently.
+ *
+ * Readable while it fits: this string lands in the database and in error messages, and
+ * `a1b2c3…#0` tells a person nothing about which test broke. Only when the plain form would
+ * exceed what the contract accepts does it fall back to a digest — and the digest covers the test
+ * id alone, so the retry stays visible and a flaky test's three attempts never collapse into one.
+ */
+declare function resultKey(testId: string, retry: number): string;
+
+/**
+ * What a CI job can tell the reporter without editing a config file.
+ *
+ * A Playwright config is committed; a CI job is not. Everything here exists so a pipeline can set
+ * the shared run key, the token and the batch size per job — the things that differ between the
+ * laptop the config was written on and the runner it executes on.
+ */
+/**
+ * Names the reporter promises but the platform cannot yet store (feature D13).
+ *
+ * They are listed rather than ignored because of how they would fail otherwise: a run's `meta`
+ * strips keys it does not know, so sending `PLUNE_ENV` there would be accepted, dropped, and look
+ * exactly like success. A client believing it saved something the server discarded is the most
+ * expensive kind of quiet — cheaper to say "not yet" out loud.
+ */
+declare const UNSUPPORTED_VARS: readonly ["PLUNE_RUN_TITLE", "PLUNE_ENV", "PLUNE_LABELS", "PLUNE_GROUP"];
+interface EnvSettings {
+    /** Config fields the environment supplied. Anything passed explicitly outranks these. */
+    config: Partial<ReporterConfig>;
+    /** This process must not close the run — several share it, or the job closes it itself. */
+    keepOpen: boolean;
+    /** Variables that were set and have nowhere to land. The caller says so once. */
+    ignored: string[];
+}
+declare function readEnv(env?: NodeJS.ProcessEnv): EnvSettings;
+
+/**
+ * What ends up in a deferred batch.
+ *
+ * Two shapes, because two things can fail. A batch refused by the platform is already resolved
+ * (`ResultSubmission`), and replay sends it as it is. A batch deferred because the platform was
+ * never reached has not been resolved at all (`PendingResult`), and replay has to look its keys
+ * up first. Flattening them into one shape would mean inventing a `testCaseId` for the second
+ * case, which is exactly what AC-11 forbids.
+ */
+type DeferredResult = ResultSubmission | PendingResult;
+/** Beside `last-run.json`, because that is where a Plune user already looks for a run. */
+declare const DEFAULT_FALLBACK_PATH: string;
+/**
+ * One batch that could not be sent.
+ *
+ * A batch rather than a result: the batch is the unit that failed, and it is the unit `plune run
+ * report` will re-send unchanged. Splitting it into results here would mean re-grouping them there
+ * against a size the platform may have changed in the meantime.
+ *
+ * `runId: null` is a real state, not a missing value — the platform was unreachable when the run
+ * was supposed to be created, so these results have no run yet and replay has to make one.
+ */
+interface DeferredBatch {
+    runId: string | null;
+    externalKey: string | null;
+    results: DeferredResult[];
+}
+/**
+ * Append a batch to the fallback file, creating its directory if nobody has yet.
+ *
+ * JSONL and synchronous, both for the same reason: a run is being abandoned when this is called,
+ * and the next thing to happen may be the process dying. A line that is already flushed stays
+ * readable no matter what happens to the ones after it, which one large JSON document rewritten
+ * on every batch would not.
+ *
+ * Nothing about the connection goes in — not the token, not the headers, not the config. The line
+ * holds who the run was and what did not reach it, which is exactly what replaying needs.
+ */
+declare function appendBatch(file: string, batch: DeferredBatch): void;
+
+/**
+ * The only thing in this package that talks to the platform.
+ *
+ * It classifies rather than throws. Every caller has to decide something different about a
+ * failure — a batch goes to the fallback file, a rejected token silences the rest of the run, a
+ * closed run is a configuration mistake worth naming — and an exception hierarchy would make each
+ * of those a `catch` that re-derives what already happened here.
+ *
+ * It also does not log. Anything printed about a failure is printed by the session, which knows
+ * the context; keeping the token's only home in this file is what makes AC-12 structural rather
+ * than a rule someone has to remember.
+ */
+type ClientFailureKind = 
+/** The token was refused. Retrying sends the same token to the same door. */
+'auth'
+/** The server understood and said no: a closed run, an impossible lifecycle transition. */
+ | 'conflict'
+/** The body was refused. It will be refused identically next time. */
+ | 'invalid'
+/** Nobody answered, or answered with their own failure. Worth another try. */
+ | 'unavailable'
+/** Everything else — reported, never retried, because we cannot say retrying would help. */
+ | 'other';
+type ClientOutcome<T> = {
+    ok: true;
+    status: number;
+    body: T;
+} | {
+    ok: false;
+    kind: ClientFailureKind;
+    status: number | null;
+    detail: string;
+};
+interface ClientOptions {
+    apiUrl: string;
+    token: string;
+    fetchImpl?: typeof fetch;
+    /** Test seam — the same idea as `fetchImpl`, so a retry test costs milliseconds, not seconds. */
+    wait?: (ms: number) => Promise<void>;
+}
+interface PlatformClient {
+    post<T>(path: string, body: unknown): Promise<ClientOutcome<T>>;
+}
+declare function createClient(opts: ClientOptions): PlatformClient;
+
+export { type AssertionRecord, type Attachment, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type SubmitCounts, UNSUPPORTED_VARS, appendBatch, createClient, readEnv, resultKey, startRun };