@wardby/cli 0.5.3 → 0.7.0

package/dist/providers/review-host/types.d.ts

@@ -12,6 +12,16 @@ export declare const HOST_ACCOUNT_PROVIDERS: readonly ReviewHostProvider[];
 export type ReviewVerdict = "APPROVE" | "CHANGES_REQUESTED" | "COMMENT";
 export type CheckConclusion = "success" | "failure" | "neutral";
 export type CommentSide = "LEFT" | "RIGHT";
+/**
+ * Where a file's patch is in a repo_pr_read result:
+ * - complete: the whole patch is in this result;
+ * - partial: one part, starting at patchOffset; the rest comes with nextPatchCursor;
+ * - later_page: not in this result; call again with nextPatchCursor;
+ * - earlier_page: delivered by an earlier call of the same cursor chain;
+ * - unavailable: the host has no patch for it (too large, binary): read it with repo_read_file;
+ * - empty: nothing to show (no line changes, a pure rename).
+ */
+export type PatchStatus = "complete" | "partial" | "later_page" | "earlier_page" | "unavailable" | "empty";
 export interface PullRequestFileView {
     filename: string;
     status: string;
@@ -19,7 +29,18 @@ export interface PullRequestFileView {
     deletions: number;
     previousFilename?: string;
     patch: string;
+    /** True for later_page, unavailable, and a partial part that the next page continues. */
     patchTruncated: boolean;
+    patchStatus: PatchStatus;
+    /** Where this part starts in the file's patch; only on partial. */
+    patchOffset?: number;
+    /** Only on partial: true when the next page continues this file, false when this part is its last. */
+    patchContinues?: boolean;
+}
+/** A patchCursor that is not one this deployment issued, or one for a head or compare that has moved on. */
+export declare class PatchCursorError extends Error {
+    readonly reason: "malformed" | "stale";
+    constructor(reason: "malformed" | "stale");
 }
 /** One of this agent's own review threads that is still unresolved. */
 export interface ReviewThreadView {
@@ -71,6 +92,12 @@ export interface PullRequestView {
     htmlUrl: string;
     /** Head sha recorded in this agent's summary comment, if it reviewed before. */
     lastReviewedSha: string | null;
+    /**
+     * The latest head this agent reviewed after reading every file (a whole, uncut list of the
+     * pull request or a delta from an earlier covered head, every source/test/config file read),
+     * whatever the verdict. The only safe sinceSha for a re-review that may APPROVE.
+     */
+    lastCoveredSha: string | null;
     /** Set when `files` is the compare of `comparedFrom...headSha` rather than the whole PR. */
     comparedFrom: string | null;
     /**
@@ -80,10 +107,26 @@ export interface PullRequestView {
      */
     baseMergedSince: boolean;
     files: PullRequestFileView[];
+    /**
+     * False when `files` is cut: the host's listing stopped at its upper bound before every
+     * changed file (on GitHub, also a compare at its 300-file limit). repo_publish_review then
+     * refuses an APPROVE of this head with file_list_truncated.
+     */
+    fileListComplete: boolean;
+    /** No patch is left to page through and none is unavailable: with earlier pages, every patch was delivered. */
+    patchesComplete: boolean;
+    /** Files whose patch is not (fully) delivered yet: later_page, unavailable, or a partial part the next page continues; in review order. */
+    truncatedFiles: string[];
+    /** Pass as repo_pr_read's patchCursor for the next page; null when nothing is left to page. */
+    nextPatchCursor: string | null;
+    /** Estimate of files with patch content still to come after this page (a partial file counts once); a later_page file may turn out empty or unavailable once loaded. */
+    remainingPatchFiles: number;
     /** This agent's own unresolved review threads on the PR (the first 100 threads are searched). */
     openThreads: ReviewThreadView[];
     /** CI on headSha (check runs and commit statuses, minus wardby's own); absent on hosts that can't read CI. */
     ci?: CiView;
+    /** Only on a wardby pull request with a pending proposal in its description comment. */
+    descriptionProposal?: DescriptionProposalView;
 }
 export interface PullRequestHead {
     headSha: string;
@@ -120,6 +163,59 @@ export type FileReadResult = {
     kind: "not_found";
     path: string;
 };
+/** One issue comment; author-written text, untrusted. */
+export interface IssueCommentView {
+    author: string | null;
+    body: string;
+    createdAt: string;
+    /** The body was cut at the per-comment cap. */
+    truncated: boolean;
+}
+/** An issue as repo_issue_read shows it. Title, body, labels, and comments are untrusted text. */
+export interface IssueView {
+    number: number;
+    title: string;
+    state: "open" | "closed";
+    body: string;
+    bodyTruncated: boolean;
+    labels: string[];
+    author: string | null;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+    /** The most recent comments, oldest first. */
+    comments: IssueCommentView[];
+    /** All comments on the issue, including any left out. */
+    totalComments: number;
+    /** Anything was cut: the body, a comment, or older comments left out. */
+    truncated: boolean;
+}
+/**
+ * wardby's proposed description on a pull request whose description wardby
+ * couldn't confirm as its own (from its description comment). `current`: the
+ * proposal is for the head being read; `not_for_this_head`: it isn't yet;
+ * `unavailable`: the comments couldn't be read.
+ */
+export type DescriptionProposalView = {
+    state: "current";
+    forHead: string;
+    runId?: string;
+    text: string;
+    truncated: boolean;
+    note: string;
+} | {
+    state: "not_for_this_head" | "unavailable";
+    note: string;
+};
+export type IssueReadResult = ({
+    kind: "issue";
+} & IssueView) | {
+    kind: "pull_request";
+    number: number;
+} | {
+    kind: "not_found";
+    number: number;
+};
 export interface FileListView {
     ref: string;
     count: number;
@@ -157,6 +253,11 @@ export interface PublishReviewInput {
      * unresolved threads on this PR are resolved; any other id is skipped.
      */
     resolveThreadIds?: string[];
+    /**
+     * headSha when this review read every file of it (see PullRequestView.lastCoveredSha); null or
+     * absent otherwise, and the host keeps the earlier covered head.
+     */
+    coveredSha?: string | null;
 }
 export type PublishReviewResult = {
     published: true;
@@ -207,12 +308,25 @@ export interface CompleteCheckInput {
     text?: string;
     detailsUrl?: string;
 }
+export type UpsertNamedCheckInput = {
+    headSha: string;
+    /** The check's fixed name, e.g. MERGE_ORDER_CHECK_NAME ("wardby merge order"); identifies which run to update. */
+    name: string;
+    title: string;
+    summary: string;
+} & ({
+    status: "in_progress";
+} | {
+    status: "completed";
+    conclusion: "success" | "failure";
+});
 /**
  * A user's effective permission on one repository, host-neutral and ranked
  * none < read < triage < write < maintain < admin. GitHub maps its
  * collaborator permission onto these directly; GitLab would map reporter ->
  * read, developer -> write, maintainer -> maintain, owner -> admin.
  */
+export type AcknowledgeOutcome = "picked_up" | "refused";
 export type HostPermission = "none" | "read" | "triage" | "write" | "maintain" | "admin";
 export declare const HOST_PERMISSION_RANK: Readonly<Record<HostPermission, number>>;
 /** A host user, by its immutable numeric id (as text) and its current login. */
@@ -222,6 +336,8 @@ export interface HostUser {
 }
 export interface CodeReviewHost {
     readonly provider: ReviewHostProvider;
+    /** The GitHub App's owner account (always served; see WARDBY_GITHUB_ALLOWED_ACCOUNTS). Hosts without an App omit it. */
+    appOwnerLogin?(): Promise<string>;
     /**
      * The user's effective permission on `repository`, asked with the App's own
      * installation credential (never a user token). Answers only for the user
@@ -236,6 +352,7 @@ export interface CodeReviewHost {
         sinceSha?: string;
         maxPatchChars: number;
         agentMarker: string;
+        patchCursor?: string;
     }): Promise<PullRequestView>;
     pullRequestHead(repository: string, prNumber: number): Promise<PullRequestHead>;
     /** CI on one commit, excluding wardby's own checks. Never throws. Hosts that can't say leave it out. */
@@ -260,6 +377,11 @@ export interface CodeReviewHost {
         maxLines: number;
     }): Promise<FileReadResult>;
     listFiles(repository: string, ref: string | undefined, pathPrefix?: string): Promise<FileListView>;
+    /** An issue and its most recent comments, read-only. Hosts without issues (a local repository) leave it out. */
+    /** `comments: false` reads the issue alone (title, body, labels), without its comments. */
+    readIssue?(repository: string, number: number, opts?: {
+        comments?: boolean;
+    }): Promise<IssueReadResult>;
     publishReview(repository: string, input: PublishReviewInput): Promise<PublishReviewResult>;
     /** `id` identifies the new comment for editComment; a reply is an "inline" comment, anything else "conversation". */
     comment(repository: string, input: CommentInput): Promise<{
@@ -268,12 +390,41 @@ export interface CodeReviewHost {
     }>;
     /** Replaces the body of a comment the App wrote. */
     editComment(repository: string, input: EditCommentInput): Promise<void>;
-    /** Marks a comment as picked up (GitHub: a 👀 reaction); a host without reactions may do nothing. */
-    acknowledge(repository: string, target: CommentRef): Promise<void>;
+    /**
+     * Marks a comment as picked up (GitHub: a 👀 reaction), or as refused (😕)
+     * when its author can see the repository but lacks the access to start a
+     * run. A host without reactions may do nothing.
+     */
+    acknowledge(repository: string, target: CommentRef, outcome?: AcknowledgeOutcome): Promise<void>;
     startCheck(repository: string, input: StartCheckInput): Promise<{
         checkId: string;
     }>;
     completeCheck(repository: string, input: CompleteCheckInput): Promise<void>;
+    /**
+     * Creates or updates, by fixed name, a check run on one commit that isn't
+     * tied to a run's own startCheck/completeCheck lifecycle (e.g. the
+     * `wardby merge order` check, recomputed fresh and reposted on demand).
+     * Finds the one this App owns among the commit's check runs with that
+     * name and patches it; creates one when none exists. Hosts that can't
+     * post checks (e.g. a local repository) leave this out.
+     */
+    upsertNamedCheck?(repository: string, input: UpsertNamedCheckInput): Promise<void>;
+    /**
+     * This App's newest check run per name on one commit (names not found are absent).
+     * At most 10 names. Hosts that can't say leave it out.
+     */
+    readOwnChecks?(repository: string, headSha: string, names: string[]): Promise<Map<string, OwnCheckView>>;
+    /**
+     * Marks a draft pull request this App authored ready for review, only while it is
+     * open, a draft, at `expectedHeadSha`, and carrying `expectedMarkerRunId` in its
+     * description's run marker (mirrors replaceRelatedSection's expectedMarkerRunId).
+     * "skipped" covers every refusal.
+     */
+    markReadyForReview?(repository: string, prNumber: number, expectedHeadSha: string, expectedMarkerRunId: string): Promise<"marked" | "skipped">;
+}
+export interface OwnCheckView {
+    status: string;
+    conclusion: string | null;
 }
 export type ReviewHostErrorCode = "host_not_installed" | "host_permission_missing" | "host_api_error" | "host_invalid_response";
 export declare class ReviewHostError extends Error {
@@ -361,6 +512,10 @@ export type HostEvent = {
     author: string;
     /** The author's immutable numeric host user id, as text; their permission is checked by it. */
     authorId: string;
+    /** GitHub's `author_association` for the author; a hint only, never a permission. */
+    authorAssociation?: string;
+    /** Whether the repository is private, when the payload says. */
+    repositoryPrivate?: boolean;
     /** The issue or PR the mention is on, when the payload carries it. */
     subject?: {
         title: string;

package/dist/providers/review-host/types.js

@@ -8,6 +8,14 @@
 export const REVIEW_HOST_PROVIDERS = ["github", "local"];
 /** Providers with host user accounts to link (link_host_account); a local repository has none. */
 export const HOST_ACCOUNT_PROVIDERS = ["github"];
+/** A patchCursor that is not one this deployment issued, or one for a head or compare that has moved on. */
+export class PatchCursorError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason === "stale" ? "patch_cursor_stale" : "patch_cursor_malformed");
+        this.reason = reason;
+    }
+}
 export const HOST_PERMISSION_RANK = {
     none: 0,
     read: 1,

package/dist/providers/storage/gcs.d.ts

@@ -0,0 +1,63 @@
+import type { Readable, Writable } from "node:stream";
+import { type BlobInfo, type BlobStore } from "./types.js";
+/** The slice of a GCS File the adapter uses (the real `File` satisfies it; tests supply an in-memory fake). */
+export interface GcsFileLike {
+    createWriteStream(options?: {
+        resumable?: boolean;
+        contentType?: string;
+    }): Writable;
+    createReadStream(): Readable;
+    getMetadata(): Promise<[
+        {
+            size?: string | number;
+            updated?: string;
+            metadata?: Record<string, unknown>;
+        },
+        ...unknown[]
+    ]>;
+    save(data: Buffer, options?: {
+        resumable?: boolean;
+        contentType?: string;
+    }): Promise<unknown>;
+    delete(options?: {
+        ignoreNotFound?: boolean;
+    }): Promise<unknown>;
+    getSignedUrl(config: {
+        version: "v4";
+        action: "read" | "write";
+        expires: number;
+    }): Promise<[string]>;
+}
+export interface GcsBucketLike {
+    file(name: string): GcsFileLike;
+}
+/**
+ * Google Cloud Storage blob store. Credentials come from Application Default Credentials (Workload Identity on
+ * GKE); no key files. Uploads are single-request (non-resumable), so an upload that is destroyed before it
+ * finishes never creates or replaces an object.
+ */
+export declare class GcsBlobStore implements BlobStore {
+    private readonly bucket;
+    constructor(bucket: GcsBucketLike);
+    /** Build a store over `bucketName` using Application Default Credentials. */
+    static forBucket(bucketName: string): GcsBlobStore;
+    private file;
+    put(key: string, body: Buffer, opts?: {
+        contentType?: string;
+    }): Promise<void>;
+    get(key: string): Promise<Buffer>;
+    delete(key: string): Promise<void>;
+    signedUrl(key: string, opts: {
+        expiresSec: number;
+        method: "GET" | "PUT";
+    }): Promise<string>;
+    putStream(key: string, body: NodeJS.ReadableStream, opts?: {
+        contentType?: string;
+        maxBytes?: number;
+    }): Promise<{
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    getStream(key: string): Promise<NodeJS.ReadableStream>;
+    head(key: string): Promise<BlobInfo | null>;
+}

package/dist/providers/storage/gcs.js

@@ -0,0 +1,69 @@
+import { pipeline } from "node:stream/promises";
+import { Storage } from "@google-cloud/storage";
+import { collectStream, createByteMeter } from "./meter.js";
+import { assertValidBlobKey, BlobStoreError } from "./types.js";
+function isNotFound(error) {
+    return error?.code === 404;
+}
+/**
+ * Google Cloud Storage blob store. Credentials come from Application Default Credentials (Workload Identity on
+ * GKE); no key files. Uploads are single-request (non-resumable), so an upload that is destroyed before it
+ * finishes never creates or replaces an object.
+ */
+export class GcsBlobStore {
+    bucket;
+    constructor(bucket) {
+        this.bucket = bucket;
+    }
+    /** Build a store over `bucketName` using Application Default Credentials. */
+    static forBucket(bucketName) {
+        return new GcsBlobStore(new Storage().bucket(bucketName));
+    }
+    file(key) {
+        assertValidBlobKey(key);
+        return this.bucket.file(key);
+    }
+    async put(key, body, opts) {
+        await this.file(key).save(body, { resumable: false, contentType: opts?.contentType });
+    }
+    async get(key) {
+        return collectStream(await this.getStream(key));
+    }
+    async delete(key) {
+        await this.file(key).delete({ ignoreNotFound: true });
+    }
+    async signedUrl(key, opts) {
+        const [url] = await this.file(key).getSignedUrl({
+            version: "v4",
+            action: opts.method === "GET" ? "read" : "write",
+            expires: Date.now() + opts.expiresSec * 1000,
+        });
+        return url;
+    }
+    async putStream(key, body, opts) {
+        const file = this.file(key);
+        const meter = createByteMeter(opts?.maxBytes);
+        // pipeline destroys every stream (including the GCS write stream) on failure, which aborts the HTTP request
+        // before the object is finalized.
+        await pipeline(body, meter.stream, file.createWriteStream({ resumable: false, contentType: opts?.contentType }));
+        return { sizeBytes: meter.size(), sha256: meter.digest() };
+    }
+    async getStream(key) {
+        const file = this.file(key);
+        // createReadStream reports a missing object asynchronously; look first so callers get a typed not_found.
+        if ((await this.head(key)) === null)
+            throw new BlobStoreError("not_found");
+        return file.createReadStream();
+    }
+    async head(key) {
+        try {
+            const [metadata] = await this.file(key).getMetadata();
+            return { sizeBytes: Number(metadata.size ?? 0), updatedAt: new Date(metadata.updated ?? 0) };
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return null;
+            throw error;
+        }
+    }
+}

package/dist/providers/storage/index.d.ts

@@ -0,0 +1,15 @@
+import type { BlobStore } from "./types.js";
+export type BlobStoreConfig = {
+    kind: "local";
+    localDir: string;
+} | {
+    kind: "gcs";
+    bucket: string;
+} | {
+    kind: "s3";
+    bucket: string;
+    region: string;
+    endpoint?: string;
+};
+/** Build the configured blob store. Cloud adapters take credentials from the environment's default chain. */
+export declare function createBlobStore(config: BlobStoreConfig): BlobStore;

package/dist/providers/storage/index.js

@@ -0,0 +1,14 @@
+import { GcsBlobStore } from "./gcs.js";
+import { LocalBlobStore } from "./local.js";
+import { S3BlobStore } from "./s3.js";
+/** Build the configured blob store. Cloud adapters take credentials from the environment's default chain. */
+export function createBlobStore(config) {
+    switch (config.kind) {
+        case "local":
+            return new LocalBlobStore(config.localDir);
+        case "gcs":
+            return GcsBlobStore.forBucket(config.bucket);
+        case "s3":
+            return S3BlobStore.forBucket(config);
+    }
+}

package/dist/providers/storage/local.d.ts

@@ -0,0 +1,24 @@
+import { type BlobInfo, type BlobStore } from "./types.js";
+/** Filesystem blob store rooted at one directory. Writes go to a temp file in the target directory, then rename (atomic). */
+export declare class LocalBlobStore implements BlobStore {
+    private readonly root;
+    constructor(root: string);
+    private pathFor;
+    private tempPathFor;
+    put(key: string, body: Buffer): Promise<void>;
+    get(key: string): Promise<Buffer>;
+    delete(key: string): Promise<void>;
+    signedUrl(key: string, _opts: {
+        expiresSec: number;
+        method: "GET" | "PUT";
+    }): Promise<string>;
+    putStream(key: string, body: NodeJS.ReadableStream, opts?: {
+        contentType?: string;
+        maxBytes?: number;
+    }): Promise<{
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    getStream(key: string): Promise<NodeJS.ReadableStream>;
+    head(key: string): Promise<BlobInfo | null>;
+}

package/dist/providers/storage/local.js

@@ -0,0 +1,92 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { createByteMeter } from "./meter.js";
+import { assertValidBlobKey, BlobStoreError } from "./types.js";
+function isNotFound(error) {
+    return error?.code === "ENOENT";
+}
+/** Filesystem blob store rooted at one directory. Writes go to a temp file in the target directory, then rename (atomic). */
+export class LocalBlobStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    pathFor(key) {
+        assertValidBlobKey(key);
+        return join(this.root, key);
+    }
+    tempPathFor(path) {
+        return join(dirname(path), `.tmp-${randomUUID()}`);
+    }
+    async put(key, body) {
+        const path = this.pathFor(key);
+        await mkdir(dirname(path), { recursive: true });
+        const temp = this.tempPathFor(path);
+        try {
+            await writeFile(temp, body);
+            await rename(temp, path);
+        }
+        catch (error) {
+            await rm(temp, { force: true });
+            throw error;
+        }
+    }
+    async get(key) {
+        try {
+            return await readFile(this.pathFor(key));
+        }
+        catch (error) {
+            if (isNotFound(error))
+                throw new BlobStoreError("not_found", "not_found", { cause: error });
+            throw error;
+        }
+    }
+    async delete(key) {
+        await rm(this.pathFor(key), { force: true });
+    }
+    async signedUrl(key, _opts) {
+        assertValidBlobKey(key);
+        throw new BlobStoreError("not_supported", "not_supported: the local blob store has no signed URLs");
+    }
+    async putStream(key, body, opts) {
+        const path = this.pathFor(key);
+        await mkdir(dirname(path), { recursive: true });
+        const temp = this.tempPathFor(path);
+        const meter = createByteMeter(opts?.maxBytes);
+        try {
+            await pipeline(body, meter.stream, createWriteStream(temp));
+            await rename(temp, path);
+        }
+        catch (error) {
+            await rm(temp, { force: true });
+            throw error;
+        }
+        return { sizeBytes: meter.size(), sha256: meter.digest() };
+    }
+    async getStream(key) {
+        const path = this.pathFor(key);
+        try {
+            await stat(path);
+        }
+        catch (error) {
+            if (isNotFound(error))
+                throw new BlobStoreError("not_found", "not_found", { cause: error });
+            throw error;
+        }
+        return createReadStream(path);
+    }
+    async head(key) {
+        try {
+            const info = await stat(this.pathFor(key));
+            return { sizeBytes: info.size, updatedAt: info.mtime };
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return null;
+            throw error;
+        }
+    }
+}

package/dist/providers/storage/meter.d.ts

@@ -0,0 +1,14 @@
+import { Transform } from "node:stream";
+import { BlobStoreError } from "./types.js";
+export interface ByteMeter {
+    stream: Transform;
+    /** Bytes seen so far. */
+    size(): number;
+    /** The blob_too_large error, once the limit tripped. */
+    limitError(): BlobStoreError | undefined;
+    /** Finish the hash; call once, after the body has ended. */
+    digest(): string;
+}
+/** A passthrough that counts bytes (normalizing string chunks), hashes them, and fails with blob_too_large past `maxBytes`. */
+export declare function createByteMeter(maxBytes: number | undefined): ByteMeter;
+export declare function collectStream(stream: NodeJS.ReadableStream): Promise<Buffer>;

package/dist/providers/storage/meter.js

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { Transform } from "node:stream";
+import { BlobStoreError } from "./types.js";
+/** A passthrough that counts bytes (normalizing string chunks), hashes them, and fails with blob_too_large past `maxBytes`. */
+export function createByteMeter(maxBytes) {
+    const hash = createHash("sha256");
+    let sizeBytes = 0;
+    let tooLarge;
+    const stream = new Transform({
+        transform(chunk, encoding, callback) {
+            // Only a string is converted; a Buffer (or any byte view) passes through without a copy.
+            const bytes = typeof chunk === "string"
+                ? Buffer.from(chunk, encoding)
+                : Buffer.isBuffer(chunk)
+                    ? chunk
+                    : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+            sizeBytes += bytes.length;
+            if (maxBytes !== undefined && sizeBytes > maxBytes) {
+                tooLarge = new BlobStoreError("blob_too_large", `blob_too_large: more than ${maxBytes} bytes`);
+                callback(tooLarge);
+                return;
+            }
+            hash.update(bytes);
+            callback(null, bytes);
+        },
+    });
+    return { stream, size: () => sizeBytes, limitError: () => tooLarge, digest: () => hash.digest("hex") };
+}
+export async function collectStream(stream) {
+    const chunks = [];
+    for await (const chunk of stream)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks);
+}

package/dist/providers/storage/s3.d.ts

@@ -0,0 +1,41 @@
+import { type BlobInfo, type BlobStore } from "./types.js";
+/** The slice of S3Client the adapter uses (the real client satisfies it; tests supply an in-memory fake). */
+export interface S3ClientLike {
+    send(command: object): Promise<unknown>;
+    readonly config: unknown;
+}
+/**
+ * S3-compatible blob store (AWS S3, MinIO via `endpoint`). Credentials come from the default AWS credential
+ * chain (Pod Identity on EKS). Streamed uploads use multipart for large bodies; S3 only exposes an object once the
+ * upload completes, so an aborted upload never replaces the previous object.
+ */
+export declare class S3BlobStore implements BlobStore {
+    private readonly client;
+    private readonly bucket;
+    constructor(client: S3ClientLike, bucket: string);
+    /** Build a store using the default credential chain. A custom `endpoint` (MinIO) switches to path-style addressing. */
+    static forBucket(settings: {
+        bucket: string;
+        region: string;
+        endpoint?: string;
+    }): S3BlobStore;
+    private keyed;
+    put(key: string, body: Buffer, opts?: {
+        contentType?: string;
+    }): Promise<void>;
+    get(key: string): Promise<Buffer>;
+    delete(key: string): Promise<void>;
+    signedUrl(key: string, opts: {
+        expiresSec: number;
+        method: "GET" | "PUT";
+    }): Promise<string>;
+    putStream(key: string, body: NodeJS.ReadableStream, opts?: {
+        contentType?: string;
+        maxBytes?: number;
+    }): Promise<{
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    getStream(key: string): Promise<NodeJS.ReadableStream>;
+    head(key: string): Promise<BlobInfo | null>;
+}