@powerhousedao/reactor-attachments 6.2.3-dev.5 → 6.2.3-dev.51

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../src/concurrency.ts","../src/progress.ts","../src/client.ts"],"sourcesContent":["/**\n * Ordered result of one batch item. `index` always mirrors the input\n * position, so callers can correlate results with inputs regardless of\n * completion order, and successes are retained when siblings fail.\n */\nexport type BatchItemResult<R> =\n  | { index: number; status: \"fulfilled\"; value: R }\n  | { index: number; status: \"rejected\"; error: unknown };\n\nexport type RunWithConcurrencyOptions<R = unknown> = {\n  /** Maximum simultaneously running workers. Must be a positive integer. */\n  concurrency: number;\n  /**\n   * Whole-batch cancellation: unstarted items are rejected with the signal's\n   * reason without ever starting, while already-started items keep running —\n   * per-item signals are the mechanism for interrupting active work.\n   */\n  signal?: AbortSignal;\n  /**\n   * Called once per item as it settles, in completion order, including items\n   * the signal skipped before they ever started. That completeness is the\n   * point: a caller counting settlements must still reach `items.length`\n   * after a whole-batch abort.\n   */\n  onSettled?: (result: BatchItemResult<R>) => void;\n};\n\n/**\n * Runs `worker` over `items` with a hard upper bound on simultaneous\n * executions. Bounding starts (not just transfers) is what keeps memory flat:\n * an item's preprocessing (hashing/buffering) only begins when a slot frees.\n */\nexport async function runWithConcurrency<T, R>(\n  items: readonly T[],\n  worker: (item: T, index: number) => Promise<R>,\n  options: RunWithConcurrencyOptions<R>,\n): Promise<BatchItemResult<R>[]> {\n  const { concurrency, signal, onSettled } = options;\n  if (!Number.isInteger(concurrency) || concurrency < 1) {\n    throw new Error(\n      `concurrency must be a positive integer, got: ${concurrency}`,\n    );\n  }\n\n  const results: BatchItemResult<R>[] = new Array<BatchItemResult<R>>(\n    items.length,\n  );\n  let nextIndex = 0;\n\n  async function runLane(): Promise<void> {\n    for (;;) {\n      const index = nextIndex++;\n      if (index >= items.length) return;\n      if (signal?.aborted) {\n        results[index] = {\n          index,\n          status: \"rejected\",\n          error: signalReason(signal),\n        };\n        onSettled?.(results[index]);\n        continue;\n      }\n      try {\n        const value = await worker(items[index], index);\n        results[index] = { index, status: \"fulfilled\", value };\n      } catch (error) {\n        results[index] = { index, status: \"rejected\", error };\n      }\n      onSettled?.(results[index]);\n    }\n  }\n\n  const lanes = Array.from(\n    { length: Math.min(concurrency, items.length) },\n    () => runLane(),\n  );\n  await Promise.all(lanes);\n  return results;\n}\n\nfunction signalReason(signal: AbortSignal): unknown {\n  return (\n    (signal as { reason?: unknown }).reason ??\n    new DOMException(\"The operation was aborted\", \"AbortError\")\n  );\n}\n","/**\n * Byte-level progress for attachment transfers.\n *\n * `loaded`/`total` are per-stage, never per-operation. A per-operation\n * denominator would have to weight hashing against transfer, and a confirmed\n * dedup would shrink it mid-flight from 2N to N — the bar would run backwards.\n * Choosing that weighting is a UI decision the client cannot make.\n */\n\nexport type AttachmentStage =\n  | \"hashing\"\n  | \"reserving\"\n  | \"uploading\"\n  | \"requesting-download-target\"\n  | \"downloading\"\n  | \"done\"\n  | \"error\";\n\nexport type AttachmentProgress = {\n  stage: AttachmentStage;\n  /** Bytes moved so far within `stage`. */\n  loaded: number;\n  /** Denominator for `stage`: file.size for uploads, header.sizeBytes for downloads. */\n  total: number | undefined;\n  /** True when the stage is running but bytes cannot (yet) be observed. */\n  indeterminate: boolean;\n  /** Only on a terminal `done` where dedup skipped the transfer entirely. */\n  deduped?: true;\n};\n\nexport type AttachmentProgressListener = (progress: AttachmentProgress) => void;\n\nexport type AttachmentProgressOptions = {\n  onProgress?: AttachmentProgressListener;\n  /** Min ms between byte events within a stage. Default 100. 0 emits every observation. */\n  throttleMs?: number;\n};\n\nexport const DEFAULT_PROGRESS_THROTTLE_MS = 100;\n\n/**\n * Fraction in 0..1 for a progress event. Indeterminate and unknown-total\n * events read as 0 — a bar cannot honestly show a position it does not know.\n * A zero total is complete by definition (the dedup case moves no bytes).\n */\nexport function progressFraction(progress: AttachmentProgress): number {\n  if (progress.indeterminate) return 0;\n  if (progress.total === undefined) return 0;\n  if (progress.total === 0) return 1;\n  const fraction = progress.loaded / progress.total;\n  if (fraction < 0) return 0;\n  return fraction > 1 ? 1 : fraction;\n}\n\nexport type ProgressEmitterOptions = AttachmentProgressOptions & {\n  /** Injected clock so throttle tests stay synchronous. */\n  now?: () => number;\n};\n\n/**\n * Emits `AttachmentProgress` for one single-item operation, upholding:\n *\n * - **I1** exactly one terminal event (`done` or `error`) — never both, never twice.\n * - **I2** on `done`: `indeterminate === false`, `total` is a number, `loaded === total`.\n * - **I3** `loaded` is non-decreasing within a stage and resets to 0 on stage change.\n * - **I4** the terminal event bypasses the throttle unconditionally.\n * - **I5** `error` carries the last known `loaded`/`total`.\n *\n * Leading edge: the first `bytes()` after a `stage()` always emits, so a bar\n * leaves 0 immediately. There is deliberately no trailing-edge timer — it\n * would leak on throw, could fire after the terminal event and violate I1's\n * ordering, and is unnecessary because `finish()` always emits\n * `loaded === total`, making a dropped last intra-stage tick invisible.\n */\nexport class ProgressEmitter {\n  private readonly listener: AttachmentProgressListener | undefined;\n  private readonly throttleMs: number;\n  private readonly now: () => number;\n\n  private currentStage: AttachmentStage | undefined;\n  private loaded = 0;\n  private total: number | undefined;\n  private emittedBytesInStage = false;\n  private lastEmitAt = Number.NEGATIVE_INFINITY;\n  private settled = false;\n\n  constructor(options?: ProgressEmitterOptions) {\n    this.listener = options?.onProgress;\n    this.throttleMs = options?.throttleMs ?? DEFAULT_PROGRESS_THROTTLE_MS;\n    this.now = options?.now ?? (() => Date.now());\n  }\n\n  /** True when a listener is attached; lets callers skip instrumentation entirely. */\n  get active(): boolean {\n    return this.listener !== undefined;\n  }\n\n  /**\n   * Enter a stage. Always emits and resets `loaded` to 0. Entry is always\n   * indeterminate: no bytes have moved yet, and whether they can be observed\n   * at all is only proven by a transport actually calling back.\n   */\n  stage(stage: AttachmentStage, options?: { total?: number }): void {\n    if (this.settled) return;\n    this.currentStage = stage;\n    this.loaded = 0;\n    this.total = options?.total;\n    this.emittedBytesInStage = false;\n    this.emit({\n      stage,\n      loaded: 0,\n      total: this.total,\n      indeterminate: true,\n    });\n  }\n\n  /**\n   * Report observed bytes within the current stage. Throttled by time, with\n   * the first observation after a stage change always emitted.\n   */\n  bytes(loaded: number, total?: number): void {\n    if (this.settled || this.currentStage === undefined) return;\n    if (total !== undefined) this.total = total;\n    if (loaded > this.loaded) this.loaded = loaded;\n\n    const leadingEdge = !this.emittedBytesInStage;\n    if (!leadingEdge && this.now() - this.lastEmitAt < this.throttleMs) return;\n    this.emittedBytesInStage = true;\n    this.emit({\n      stage: this.currentStage,\n      loaded: this.loaded,\n      total: this.total,\n      indeterminate: false,\n    });\n  }\n\n  /**\n   * Terminal success. `total` defaults to the bytes actually seen so a stage\n   * with no known denominator still satisfies I2.\n   */\n  finish(override?: { loaded?: number; total?: number; deduped?: true }): void {\n    if (this.settled) return;\n    this.settled = true;\n    const total = override?.total ?? this.total ?? this.loaded;\n    const loaded = override?.loaded ?? total;\n    this.emit({\n      stage: \"done\",\n      loaded,\n      total,\n      indeterminate: false,\n      ...(override?.deduped ? { deduped: true as const } : {}),\n    });\n  }\n\n  /** Terminal success for a confirmed dedup: no bytes moved, and none needed to. */\n  finishDeduped(): void {\n    this.finish({ loaded: 0, total: 0, deduped: true });\n  }\n\n  /** Terminal failure, carrying the last known byte counts. */\n  fail(): void {\n    if (this.settled) return;\n    this.settled = true;\n    this.emit({\n      stage: \"error\",\n      loaded: this.loaded,\n      total: this.total,\n      indeterminate: false,\n    });\n  }\n\n  private emit(progress: AttachmentProgress): void {\n    this.lastEmitAt = this.now();\n    this.listener?.(progress);\n  }\n}\n\nexport type ByteProgressHooks = {\n  /** Cumulative bytes handed to the consumer. */\n  onBytes?: (loaded: number) => void;\n  /** The source ended and every byte reached the consumer. */\n  onDone?: () => void;\n  onError?: (error: unknown) => void;\n};\n\n/**\n * Count bytes as a consumer reads them.\n *\n * Uses the manual-reader form rather than `pipeThrough`, whose internal queue\n * reads far ahead of the consumer and would make `loaded` overstate what was\n * actually received. `highWaterMark: 0` is load-bearing for the same reason:\n * at the default of 1 the wrapper pulls one chunk the instant it is\n * constructed, so a caller who never reads still sees bytes counted.\n *\n * `cancel` propagates to the source, which is what keeps reader refcounts\n * (e.g. `KyselyAttachmentStore`'s) correct. Cancelling is an abandonment, not\n * a completion, so it reports `onError` — never `onDone` — carrying the\n * cancel reason the way an `AbortSignal` carries its own, with the DOM's\n * default `AbortError` when the canceller gave none.\n *\n * Returns `source` unchanged when no hook is supplied, so a caller with no\n * listener pays nothing.\n */\nexport function withByteProgress(\n  source: ReadableStream<Uint8Array>,\n  hooks: ByteProgressHooks,\n): ReadableStream<Uint8Array> {\n  if (!hooks.onBytes && !hooks.onDone && !hooks.onError) return source;\n\n  let loaded = 0;\n  let cancelled = false;\n  const reader = source.getReader();\n  return new ReadableStream<Uint8Array>(\n    {\n      async pull(controller) {\n        try {\n          const { done, value } = await reader.read();\n          // A cancel that lands while this read is in flight resolves it as\n          // `done`, and closes the stream. Bailing out here is what stops an\n          // abandoned transfer from reporting completion, and stops the\n          // already-closed controller from throwing a fabricated error into\n          // the catch below.\n          if (cancelled) return;\n          if (done) {\n            hooks.onDone?.();\n            controller.close();\n            return;\n          }\n          loaded += value.byteLength;\n          hooks.onBytes?.(loaded);\n          controller.enqueue(value);\n        } catch (err) {\n          if (cancelled) return;\n          hooks.onError?.(err);\n          controller.error(err);\n        }\n      },\n      cancel(reason) {\n        cancelled = true;\n        reader.cancel(reason).catch(() => {});\n        hooks.onError?.(reason ?? abortError());\n      },\n    },\n    { highWaterMark: 0 },\n  );\n}\n\n/** What an `AbortSignal` carries when `abort()` is called with no reason. */\nfunction abortError(): DOMException {\n  return new DOMException(\"The operation was aborted\", \"AbortError\");\n}\n","import type { AttachmentHash, AttachmentRef } from \"@powerhousedao/reactor\";\nimport {\n  runWithConcurrency,\n  type BatchItemResult,\n  type RunWithConcurrencyOptions,\n} from \"./concurrency.js\";\nimport { AttachmentAlreadyExists } from \"./errors.js\";\nexport type { AttachmentTransferStage } from \"./errors.js\";\nexport {\n  runWithConcurrency,\n  type BatchItemResult,\n  type RunWithConcurrencyOptions,\n} from \"./concurrency.js\";\nimport type { IAttachmentService, IAttachmentUpload } from \"./interfaces.js\";\nimport {\n  ProgressEmitter,\n  withByteProgress,\n  type AttachmentProgress,\n  type AttachmentProgressOptions,\n} from \"./progress.js\";\nimport { createRef } from \"./ref.js\";\nimport type {\n  AttachmentHeader,\n  AttachmentResponse,\n  AttachmentSendOptions,\n  AttachmentUploadResult,\n  HashFirstReserveAttachmentOptions,\n} from \"./types.js\";\n\nexport { AttachmentService } from \"./attachment-service.js\";\nexport {\n  AttachmentAlreadyExists,\n  AttachmentNotFound,\n  AttachmentPending,\n  AttachmentTransferError,\n  HashMismatch,\n  InvalidAttachmentRef,\n  ReservationNotFound,\n  SizeMismatch,\n  UploadTooLarge,\n} from \"./errors.js\";\nexport type {\n  IAttachmentReader,\n  IAttachmentService,\n  IAttachmentStore,\n  IAttachmentTransport,\n  IAttachmentTransportFactory,\n  IAttachmentUpload,\n  IAttachmentUploadFactory,\n  IReservationStore,\n} from \"./interfaces.js\";\nexport { parseRef, createRef } from \"./ref.js\";\nexport type { ParsedRef } from \"./ref.js\";\nexport type {\n  AttachmentDownloadOptions,\n  AttachmentDownloadTarget,\n  AttachmentDownloadTargetOptions,\n  AttachmentHeader,\n  AttachmentMetadata,\n  AttachmentResponse,\n  AttachmentSendOptions,\n  AttachmentStatus,\n  AttachmentTransportConfig,\n  AttachmentUploadResult,\n  AttachmentTargetHeaders,\n  AttachmentUploadTarget,\n  HashFirstReserveAttachmentOptions,\n  UploadFirstReserveAttachmentOptions,\n  Reservation,\n  ReserveAttachmentOptions,\n  TransportFetchResult,\n  TransportResponse,\n} from \"./types.js\";\nexport {\n  parseAttachmentDownloadTarget,\n  parseAttachmentUploadTarget,\n} from \"./targets.js\";\nexport {\n  SwitchboardAttachmentTransport,\n  type SwitchboardTransportConfig,\n  RemoteReservationStore,\n  type SwitchboardClientConfig,\n  RemoteAttachmentUpload,\n  RemoteAttachmentUploadFactory,\n  RemoteAttachmentStore,\n  createRemoteAttachmentService,\n  createFetchUploadTransport,\n  createXhrUploadTransport,\n  type AttachmentUploadRequest,\n  type AttachmentUploadResponse,\n  type AttachmentUploadTransport,\n  type XhrUploadTransportOptions,\n} from \"./switchboard/index.js\";\nexport { NullAttachmentTransport } from \"./null-attachment-transport.js\";\nexport {\n  DEFAULT_PROGRESS_THROTTLE_MS,\n  progressFraction,\n  ProgressEmitter,\n  withByteProgress,\n  type AttachmentProgress,\n  type AttachmentProgressListener,\n  type AttachmentProgressOptions,\n  type AttachmentStage,\n  type ByteProgressHooks,\n  type ProgressEmitterOptions,\n} from \"./progress.js\";\n\nexport type PreprocessResult = {\n  ref: AttachmentRef;\n  hash: AttachmentHash;\n  sizeBytes: number;\n  options: HashFirstReserveAttachmentOptions;\n  data: ReadableStream<Uint8Array>;\n  stream: () => ReadableStream<Uint8Array>;\n};\n\nexport type AttachmentUploadInput = {\n  file: Blob;\n  fileName?: string;\n  mimeType?: string;\n  /** Per-item cancellation, checked between stages. */\n  signal?: AbortSignal;\n};\n\n/**\n * Upload bytes that were already hashed by a separate `preprocess()` call.\n *\n * This is the canonical two-call flow: the ref must reach the document before\n * the bytes are committed, so callers preprocess, dispatch the operation, then\n * upload. Passing the result back in skips the hashing stage rather than\n * faking a zero-millisecond one.\n */\nexport type AttachmentPreprocessedUploadInput = {\n  preprocessed: PreprocessResult;\n  signal?: AbortSignal;\n};\n\n/**\n * Every remote download names the document that authorizes its ref; batches\n * may freely mix documents because the anchor travels with each item.\n */\nexport type AttachmentDownloadInput = {\n  documentId: string;\n  ref: AttachmentRef;\n  signal?: AbortSignal;\n};\n\n/**\n * The document keeps its own name and type for an attachment (the same\n * bytes may appear under different names in different documents), so the\n * blob-producing conveniences let callers override what the server header\n * reports from upload time.\n */\nexport type AttachmentBlobOptions = {\n  mimeType?: string;\n};\n\nexport type AttachmentSaveOptions = {\n  fileName?: string;\n  mimeType?: string;\n};\n\nexport type AttachmentBlobResult = {\n  blob: Blob;\n  header: AttachmentHeader;\n};\n\nexport type AttachmentObjectUrl = {\n  /** Ready for img/iframe/video src. Pins memory until revoke() is called. */\n  url: string;\n  header: AttachmentHeader;\n  revoke: () => void;\n};\n\nexport type AttachmentShareLinkInput = {\n  documentId: string;\n  ref: AttachmentRef;\n  /** Requested link lifetime in seconds; the server clamps to its maximum. */\n  expiresIn?: number;\n  signal?: AbortSignal;\n};\n\n/**\n * A self-contained public URL: anyone holding it can fetch the bytes until\n * expiresAtUtc, with no login and no document access. Minting one requires\n * document read access; once minted it cannot be revoked before expiry.\n */\nexport type AttachmentShareLink = {\n  url: string;\n  expiresAtUtc: string;\n};\n\n/**\n * Batch progress is per item, carrying the item's `index`. There is\n * deliberately no batch-wide byte total: weighting items against each other is\n * a presentation decision the client cannot make, and a confirmed dedup would\n * shrink the denominator mid-flight.\n */\nexport type AttachmentBatchOptions = {\n  /** Bounds preprocessing and transfer together. Defaults to 4. */\n  concurrency?: number;\n  /** Whole-batch cancellation: stops unstarted items. */\n  signal?: AbortSignal;\n  onProgress?: (progress: AttachmentProgress & { index: number }) => void;\n  /**\n   * Fired as each item settles, including items the signal skipped before they\n   * started, so `settled` always reaches `total`.\n   */\n  onItemSettled?: (counts: AttachmentBatchCounts) => void;\n  /** Min ms between byte events, applied per item rather than batch-wide. */\n  throttleMs?: number;\n};\n\nexport type AttachmentBatchCounts = {\n  settled: number;\n  completed: number;\n  failed: number;\n  total: number;\n};\n\nexport const DEFAULT_ATTACHMENT_BATCH_CONCURRENCY = 4;\n\nexport interface IAttachmentClient {\n  preprocess(\n    file: Blob,\n    opts?: { fileName?: string; mimeType?: string },\n  ): Promise<PreprocessResult>;\n  reserve(\n    options: HashFirstReserveAttachmentOptions,\n    send: (handle: IAttachmentUpload) => Promise<AttachmentUploadResult>,\n  ): Promise<AttachmentUploadResult>;\n  /**\n   * Hash, reserve, and transfer one file; a confirmed dedup skips the transfer\n   * and reports a terminal `done` carrying `deduped: true` and zero bytes.\n   *\n   * Also accepts an already-preprocessed payload, so the canonical\n   * preprocess -> dispatch -> upload flow reports progress too.\n   */\n  upload(\n    input: AttachmentUploadInput | AttachmentPreprocessedUploadInput,\n    options?: AttachmentProgressOptions,\n  ): Promise<AttachmentUploadResult>;\n  /**\n   * Document-authorized download of one ref.\n   *\n   * Resolves as soon as the byte stream is available, with `downloading` as\n   * the last event emitted and `loaded: 0`. Byte events and the terminal\n   * `done` arrive as the caller reads the stream — and never arrive at all if\n   * the caller abandons it.\n   */\n  download(\n    input: AttachmentDownloadInput,\n    options?: AttachmentProgressOptions,\n  ): Promise<AttachmentResponse>;\n  /**\n   * Document-authorized download materialized as a typed Blob. The Blob's\n   * type comes from the server header unless overridden — that's what makes\n   * browsers render PDFs inline and images correctly.\n   */\n  downloadBlob(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions & AttachmentProgressOptions,\n  ): Promise<AttachmentBlobResult>;\n  /**\n   * Download and hand the bytes to the browser's save-file flow. Browser\n   * only. fileName defaults to the server header's; pass the document's own\n   * name for per-document naming.\n   */\n  saveAttachment(\n    input: AttachmentDownloadInput,\n    options?: AttachmentSaveOptions & AttachmentProgressOptions,\n  ): Promise<void>;\n  /**\n   * Download and expose the bytes as an object URL for inline rendering\n   * (img/iframe/video src). Callers MUST call revoke() when done — the URL\n   * pins the blob in memory until then.\n   */\n  downloadObjectUrl(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions & AttachmentProgressOptions,\n  ): Promise<AttachmentObjectUrl>;\n  /**\n   * Mint a public share link: a presigned URL anyone can fetch until it\n   * expires, with no login. Authorized exactly like a download (document\n   * read access + the reference index). Requires a presigned-capable\n   * storage backend (S3); rejects when the server answers with an\n   * authenticated switchboard target, which would not be public.\n   */\n  getShareLink(input: AttachmentShareLinkInput): Promise<AttachmentShareLink>;\n  uploadMany(\n    inputs: readonly AttachmentUploadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentUploadResult>[]>;\n  downloadMany(\n    inputs: readonly AttachmentDownloadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentResponse>[]>;\n}\n\n/**\n * Duck-typed dedup detection: bundlers (notably Vite dev pre-bundling) can\n * load two copies of this package's error classes, one for the service and\n * one for the client wrapper, making a plain instanceof check miss the\n * cross-copy throw. Name plus payload shape identifies the error reliably.\n */\nfunction isAttachmentAlreadyExists(\n  err: unknown,\n): err is AttachmentAlreadyExists {\n  if (err instanceof AttachmentAlreadyExists) return true;\n  return (\n    err instanceof Error &&\n    err.name === \"AttachmentAlreadyExists\" &&\n    typeof (err as { hash?: unknown }).hash === \"string\" &&\n    typeof (err as { ref?: unknown }).ref === \"string\"\n  );\n}\n\nfunction streamFromBuffer(buf: Uint8Array): ReadableStream<Uint8Array> {\n  return new ReadableStream({\n    start(controller) {\n      controller.enqueue(buf);\n      controller.close();\n    },\n  });\n}\n\n/** Stamps an item's index onto its progress events. */\nfunction itemProgress(\n  options: AttachmentBatchOptions | undefined,\n  index: number,\n): AttachmentProgressOptions | undefined {\n  if (!options?.onProgress && options?.throttleMs === undefined) {\n    return undefined;\n  }\n  return {\n    ...(options.onProgress\n      ? {\n          onProgress: (progress: AttachmentProgress) =>\n            options.onProgress?.({ ...progress, index }),\n        }\n      : {}),\n    ...(options.throttleMs !== undefined\n      ? { throttleMs: options.throttleMs }\n      : {}),\n  };\n}\n\nfunction batchRunOptions<R>(\n  total: number,\n  options: AttachmentBatchOptions | undefined,\n): RunWithConcurrencyOptions<R> {\n  const onItemSettled = options?.onItemSettled;\n  let settled = 0;\n  let completed = 0;\n  let failed = 0;\n  return {\n    concurrency: options?.concurrency ?? DEFAULT_ATTACHMENT_BATCH_CONCURRENCY,\n    ...(options?.signal ? { signal: options.signal } : {}),\n    ...(onItemSettled\n      ? {\n          onSettled: (result: BatchItemResult<R>) => {\n            settled += 1;\n            if (result.status === \"fulfilled\") completed += 1;\n            else failed += 1;\n            onItemSettled({ settled, completed, failed, total });\n          },\n        }\n      : {}),\n  };\n}\n\nclass AttachmentClientImpl implements IAttachmentClient {\n  constructor(private readonly service: IAttachmentService) {}\n\n  async preprocess(\n    file: Blob,\n    opts?: { fileName?: string; mimeType?: string },\n  ): Promise<PreprocessResult> {\n    const buf = await file.arrayBuffer();\n    const bytes = new Uint8Array(buf);\n    const digest = await globalThis.crypto.subtle.digest(\"SHA-256\", bytes);\n    const hash = Array.from(new Uint8Array(digest))\n      .map((b) => b.toString(16).padStart(2, \"0\"))\n      .join(\"\") as AttachmentHash;\n    const ref = createRef(hash);\n    const sizeBytes = file.size;\n    const mimeType = opts?.mimeType ?? file.type;\n    const fileName =\n      opts?.fileName ?? (file instanceof File ? file.name : \"attachment\");\n    const options: HashFirstReserveAttachmentOptions = {\n      mimeType,\n      fileName,\n      clientHash: hash,\n      sizeBytes,\n    };\n    const data = streamFromBuffer(bytes);\n    const stream = (): ReadableStream<Uint8Array> => streamFromBuffer(bytes);\n    return { ref, hash, sizeBytes, options, data, stream };\n  }\n\n  /**\n   * Reserve, distinguishing a confirmed dedup from a live upload handle in the\n   * type rather than with a flag: the two outcomes move a different number of\n   * bytes, and every caller has to account for that.\n   */\n  private async reserveOrDedup(\n    options: HashFirstReserveAttachmentOptions,\n  ): Promise<\n    | { kind: \"handle\"; handle: IAttachmentUpload }\n    | { kind: \"deduped\"; result: AttachmentUploadResult }\n  > {\n    try {\n      return { kind: \"handle\", handle: await this.service.reserve(options) };\n    } catch (err) {\n      if (!isAttachmentAlreadyExists(err)) throw err;\n      const header = await this.service.stat(err.ref);\n      return {\n        kind: \"deduped\",\n        result: { hash: err.hash, ref: err.ref, header },\n      };\n    }\n  }\n\n  async reserve(\n    options: HashFirstReserveAttachmentOptions,\n    send: (handle: IAttachmentUpload) => Promise<AttachmentUploadResult>,\n  ): Promise<AttachmentUploadResult> {\n    const outcome = await this.reserveOrDedup(options);\n    if (outcome.kind === \"deduped\") return outcome.result;\n    return send(outcome.handle);\n  }\n\n  async upload(\n    input: AttachmentUploadInput | AttachmentPreprocessedUploadInput,\n    options?: AttachmentProgressOptions,\n  ): Promise<AttachmentUploadResult> {\n    const emitter = new ProgressEmitter(options);\n    const signal = input.signal;\n    try {\n      signal?.throwIfAborted();\n\n      let preprocessed: PreprocessResult;\n      if (\"preprocessed\" in input) {\n        preprocessed = input.preprocessed;\n      } else {\n        // Hashing is genuinely unobservable: preprocess() runs one\n        // crypto.subtle.digest over the whole buffer and WebCrypto has no\n        // streaming digest. The stage is still reported, with a denominator\n        // and indeterminate never cleared, so a UI can name what it waits on.\n        emitter.stage(\"hashing\", { total: input.file.size });\n        preprocessed = await this.preprocess(input.file, {\n          ...(input.fileName !== undefined ? { fileName: input.fileName } : {}),\n          ...(input.mimeType !== undefined ? { mimeType: input.mimeType } : {}),\n        });\n      }\n      const sizeBytes = preprocessed.sizeBytes;\n\n      signal?.throwIfAborted();\n      emitter.stage(\"reserving\");\n      const outcome = await this.reserveOrDedup(preprocessed.options);\n\n      // A confirmed dedup never enters `uploading` — the server already holds\n      // these bytes, so none are sent. Reporting zero of zero keeps the byte\n      // model honest instead of stalling at 0 and then jumping to done.\n      if (outcome.kind === \"deduped\") {\n        emitter.finishDeduped();\n        return outcome.result;\n      }\n\n      signal?.throwIfAborted();\n      emitter.stage(\"uploading\", { total: sizeBytes });\n      // `onProgress` only when someone is listening. The XHR transport keys\n      // its `upload.onprogress` registration off the option being present, and\n      // that registration alone forces a CORS preflight on a presigned PUT —\n      // a cost an unwatched upload must not pay for a callback that would\n      // discard every event anyway.\n      const sendOptions: AttachmentSendOptions = {\n        ...(emitter.active\n          ? {\n              onProgress: (loaded: number, total?: number) =>\n                emitter.bytes(loaded, total ?? sizeBytes),\n            }\n          : {}),\n        ...(signal ? { signal } : {}),\n      };\n      const result = await outcome.handle.send(\n        preprocessed.stream(),\n        sendOptions,\n      );\n      emitter.finish();\n      return result;\n    } catch (err) {\n      emitter.fail();\n      throw err;\n    }\n  }\n\n  /**\n   * The single site where download bytes are instrumented.\n   *\n   * It sits here, above the service, rather than in any store or transport:\n   * one logical get can be several byte streams underneath (an evicted\n   * attachment is fetched from the transport, written to disk, then re-read),\n   * so counting lower down would double-count that path and still miss\n   * local-filesystem reads. Wrapping what `service.get` returns covers the\n   * presigned, switchboard, legacy and local paths by construction, and\n   * `downloadBlob`/`saveAttachment`/`downloadObjectUrl` inherit it.\n   */\n  private async getWithProgress(\n    input: AttachmentDownloadInput,\n    emitter: ProgressEmitter,\n  ): Promise<AttachmentResponse> {\n    const { header, body } = await this.service.get(input.ref, {\n      documentId: input.documentId,\n      signal: input.signal,\n    });\n    emitter.stage(\"downloading\", { total: header.sizeBytes });\n    if (!emitter.active) return { header, body };\n    return {\n      header,\n      body: withByteProgress(body, {\n        onBytes: (loaded) => emitter.bytes(loaded),\n        onDone: () => emitter.finish(),\n        onError: () => emitter.fail(),\n      }),\n    };\n  }\n\n  async download(\n    input: AttachmentDownloadInput,\n    options?: AttachmentProgressOptions,\n  ): Promise<AttachmentResponse> {\n    const emitter = new ProgressEmitter(options);\n    try {\n      input.signal?.throwIfAborted();\n      emitter.stage(\"requesting-download-target\");\n      return await this.getWithProgress(input, emitter);\n    } catch (err) {\n      emitter.fail();\n      throw err;\n    }\n  }\n\n  async downloadBlob(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions & AttachmentProgressOptions,\n  ): Promise<AttachmentBlobResult> {\n    const emitter = new ProgressEmitter(options);\n    try {\n      input.signal?.throwIfAborted();\n      emitter.stage(\"requesting-download-target\");\n      const { header, body } = await this.getWithProgress(input, emitter);\n      const reader = body.getReader();\n      const chunks: BlobPart[] = [];\n      for (;;) {\n        const { done, value } = await reader.read();\n        if (done) break;\n        chunks.push(value as BlobPart);\n      }\n      const blob = new Blob(chunks, {\n        type: options?.mimeType ?? header.mimeType,\n      });\n      // Draining the stream already finished the emitter; latching makes this\n      // a no-op there, and a guarantee for any body that closes without one.\n      emitter.finish();\n      return { blob, header };\n    } catch (err) {\n      emitter.fail();\n      throw err;\n    }\n  }\n\n  async saveAttachment(\n    input: AttachmentDownloadInput,\n    options?: AttachmentSaveOptions & AttachmentProgressOptions,\n  ): Promise<void> {\n    if (typeof document === \"undefined\") {\n      throw new Error(\n        \"saveAttachment requires a browser environment; use downloadBlob elsewhere\",\n      );\n    }\n    const { blob, header } = await this.downloadBlob(input, options);\n    const url = URL.createObjectURL(blob);\n    try {\n      const anchor = document.createElement(\"a\");\n      anchor.href = url;\n      anchor.download = options?.fileName ?? header.fileName;\n      anchor.click();\n    } finally {\n      URL.revokeObjectURL(url);\n    }\n  }\n\n  async downloadObjectUrl(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions & AttachmentProgressOptions,\n  ): Promise<AttachmentObjectUrl> {\n    const { blob, header } = await this.downloadBlob(input, options);\n    const url = URL.createObjectURL(blob);\n    let revoked = false;\n    return {\n      url,\n      header,\n      revoke: () => {\n        if (revoked) return;\n        revoked = true;\n        URL.revokeObjectURL(url);\n      },\n    };\n  }\n\n  async getShareLink(\n    input: AttachmentShareLinkInput,\n  ): Promise<AttachmentShareLink> {\n    input.signal?.throwIfAborted();\n    const target = await this.service.getDownloadTarget(input.ref, {\n      documentId: input.documentId,\n      ...(input.expiresIn !== undefined ? { expiresIn: input.expiresIn } : {}),\n      ...(input.signal !== undefined ? { signal: input.signal } : {}),\n    });\n    if (target.kind !== \"presigned-get\") {\n      throw new Error(\n        \"Public share links require a presigned-capable storage backend (S3); this server answered with an authenticated target\",\n      );\n    }\n    return { url: target.url, expiresAtUtc: target.expiresAtUtc };\n  }\n\n  uploadMany(\n    inputs: readonly AttachmentUploadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentUploadResult>[]> {\n    return runWithConcurrency(\n      inputs,\n      (input, index) => this.upload(input, itemProgress(options, index)),\n      batchRunOptions(inputs.length, options),\n    );\n  }\n\n  /**\n   * `concurrency` bounds download-target negotiation, not simultaneous byte\n   * transfer: each item resolves when its stream is handed over, and the bytes\n   * move only as the caller reads. Byte progress makes that pre-existing\n   * behavior visible; it does not change it.\n   */\n  downloadMany(\n    inputs: readonly AttachmentDownloadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentResponse>[]> {\n    return runWithConcurrency(\n      inputs,\n      (input, index) => this.download(input, itemProgress(options, index)),\n      batchRunOptions(inputs.length, options),\n    );\n  }\n}\n\nexport function createAttachmentClient(\n  service: IAttachmentService,\n): IAttachmentClient {\n  return new AttachmentClientImpl(service);\n}\n"],"mappings":"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"}
+{"version":3,"file":"client.js","names":[],"sources":["../src/concurrency.ts","../src/progress.ts","../src/client.ts"],"sourcesContent":["/**\n * Ordered result of one batch item. `index` always mirrors the input\n * position, so callers can correlate results with inputs regardless of\n * completion order, and successes are retained when siblings fail.\n */\nexport type BatchItemResult<R> =\n  | { index: number; status: \"fulfilled\"; value: R }\n  | { index: number; status: \"rejected\"; error: unknown };\n\nexport type RunWithConcurrencyOptions<R = unknown> = {\n  /** Maximum simultaneously running workers. Must be a positive integer. */\n  concurrency: number;\n  /**\n   * Whole-batch cancellation: unstarted items are rejected with the signal's\n   * reason without ever starting, while already-started items keep running —\n   * per-item signals are the mechanism for interrupting active work.\n   */\n  signal?: AbortSignal;\n  /**\n   * Called once per item as it settles, in completion order, including items\n   * the signal skipped before they ever started. That completeness is the\n   * point: a caller counting settlements must still reach `items.length`\n   * after a whole-batch abort.\n   */\n  onSettled?: (result: BatchItemResult<R>) => void;\n};\n\n/**\n * Runs `worker` over `items` with a hard upper bound on simultaneous\n * executions. Bounding starts (not just transfers) is what keeps memory flat:\n * an item's preprocessing (hashing/buffering) only begins when a slot frees.\n */\nexport async function runWithConcurrency<T, R>(\n  items: readonly T[],\n  worker: (item: T, index: number) => Promise<R>,\n  options: RunWithConcurrencyOptions<R>,\n): Promise<BatchItemResult<R>[]> {\n  const { concurrency, signal, onSettled } = options;\n  if (!Number.isInteger(concurrency) || concurrency < 1) {\n    throw new Error(\n      `concurrency must be a positive integer, got: ${concurrency}`,\n    );\n  }\n\n  const results: BatchItemResult<R>[] = new Array<BatchItemResult<R>>(\n    items.length,\n  );\n  let nextIndex = 0;\n\n  async function runLane(): Promise<void> {\n    for (;;) {\n      const index = nextIndex++;\n      if (index >= items.length) return;\n      if (signal?.aborted) {\n        results[index] = {\n          index,\n          status: \"rejected\",\n          error: signalReason(signal),\n        };\n        onSettled?.(results[index]);\n        continue;\n      }\n      try {\n        const value = await worker(items[index], index);\n        results[index] = { index, status: \"fulfilled\", value };\n      } catch (error) {\n        results[index] = { index, status: \"rejected\", error };\n      }\n      onSettled?.(results[index]);\n    }\n  }\n\n  const lanes = Array.from(\n    { length: Math.min(concurrency, items.length) },\n    () => runLane(),\n  );\n  await Promise.all(lanes);\n  return results;\n}\n\nfunction signalReason(signal: AbortSignal): unknown {\n  return (\n    (signal as { reason?: unknown }).reason ??\n    new DOMException(\"The operation was aborted\", \"AbortError\")\n  );\n}\n","/**\n * Byte-level progress for attachment transfers.\n *\n * `loaded`/`total` are per-stage, never per-operation. A per-operation\n * denominator would have to weight hashing against transfer, and a confirmed\n * dedup would shrink it mid-flight from 2N to N — the bar would run backwards.\n * Choosing that weighting is a UI decision the client cannot make.\n */\n\nexport type AttachmentStage =\n  | \"hashing\"\n  | \"reserving\"\n  | \"uploading\"\n  | \"requesting-download-target\"\n  | \"downloading\"\n  | \"done\"\n  | \"error\";\n\nexport type AttachmentProgress = {\n  stage: AttachmentStage;\n  /** Bytes moved so far within `stage`. */\n  loaded: number;\n  /** Denominator for `stage`: file.size for uploads, header.sizeBytes for downloads. */\n  total: number | undefined;\n  /** True when the stage is running but bytes cannot (yet) be observed. */\n  indeterminate: boolean;\n  /** Only on a terminal `done` where dedup skipped the transfer entirely. */\n  deduped?: true;\n};\n\nexport type AttachmentProgressListener = (progress: AttachmentProgress) => void;\n\nexport type AttachmentProgressOptions = {\n  onProgress?: AttachmentProgressListener;\n  /** Min ms between byte events within a stage. Default 100. 0 emits every observation. */\n  throttleMs?: number;\n};\n\nexport const DEFAULT_PROGRESS_THROTTLE_MS = 100;\n\n/**\n * Fraction in 0..1 for a progress event. Indeterminate and unknown-total\n * events read as 0 — a bar cannot honestly show a position it does not know.\n * A zero total is complete by definition (the dedup case moves no bytes).\n */\nexport function progressFraction(progress: AttachmentProgress): number {\n  if (progress.indeterminate) return 0;\n  if (progress.total === undefined) return 0;\n  if (progress.total === 0) return 1;\n  const fraction = progress.loaded / progress.total;\n  if (fraction < 0) return 0;\n  return fraction > 1 ? 1 : fraction;\n}\n\nexport type ProgressEmitterOptions = AttachmentProgressOptions & {\n  /** Injected clock so throttle tests stay synchronous. */\n  now?: () => number;\n};\n\n/**\n * Emits `AttachmentProgress` for one single-item operation, upholding:\n *\n * - **I1** exactly one terminal event (`done` or `error`) — never both, never twice.\n * - **I2** on `done`: `indeterminate === false`, `total` is a number, `loaded === total`.\n * - **I3** `loaded` is non-decreasing within a stage and resets to 0 on stage change.\n * - **I4** the terminal event bypasses the throttle unconditionally.\n * - **I5** `error` carries the last known `loaded`/`total`.\n *\n * Leading edge: the first `bytes()` after a `stage()` always emits, so a bar\n * leaves 0 immediately. There is deliberately no trailing-edge timer — it\n * would leak on throw, could fire after the terminal event and violate I1's\n * ordering, and is unnecessary because `finish()` always emits\n * `loaded === total`, making a dropped last intra-stage tick invisible.\n */\nexport class ProgressEmitter {\n  private readonly listener: AttachmentProgressListener | undefined;\n  private readonly throttleMs: number;\n  private readonly now: () => number;\n\n  private currentStage: AttachmentStage | undefined;\n  private loaded = 0;\n  private total: number | undefined;\n  private emittedBytesInStage = false;\n  private lastEmitAt = Number.NEGATIVE_INFINITY;\n  private settled = false;\n\n  constructor(options?: ProgressEmitterOptions) {\n    this.listener = options?.onProgress;\n    this.throttleMs = options?.throttleMs ?? DEFAULT_PROGRESS_THROTTLE_MS;\n    this.now = options?.now ?? (() => Date.now());\n  }\n\n  /** True when a listener is attached; lets callers skip instrumentation entirely. */\n  get active(): boolean {\n    return this.listener !== undefined;\n  }\n\n  /**\n   * Enter a stage. Always emits and resets `loaded` to 0. Entry is always\n   * indeterminate: no bytes have moved yet, and whether they can be observed\n   * at all is only proven by a transport actually calling back.\n   */\n  stage(stage: AttachmentStage, options?: { total?: number }): void {\n    if (this.settled) return;\n    this.currentStage = stage;\n    this.loaded = 0;\n    this.total = options?.total;\n    this.emittedBytesInStage = false;\n    this.emit({\n      stage,\n      loaded: 0,\n      total: this.total,\n      indeterminate: true,\n    });\n  }\n\n  /**\n   * Report observed bytes within the current stage. Throttled by time, with\n   * the first observation after a stage change always emitted.\n   */\n  bytes(loaded: number, total?: number): void {\n    if (this.settled || this.currentStage === undefined) return;\n    if (total !== undefined) this.total = total;\n    if (loaded > this.loaded) this.loaded = loaded;\n\n    const leadingEdge = !this.emittedBytesInStage;\n    if (!leadingEdge && this.now() - this.lastEmitAt < this.throttleMs) return;\n    this.emittedBytesInStage = true;\n    this.emit({\n      stage: this.currentStage,\n      loaded: this.loaded,\n      total: this.total,\n      indeterminate: false,\n    });\n  }\n\n  /**\n   * Terminal success. `total` defaults to the bytes actually seen so a stage\n   * with no known denominator still satisfies I2.\n   */\n  finish(override?: { loaded?: number; total?: number; deduped?: true }): void {\n    if (this.settled) return;\n    this.settled = true;\n    const total = override?.total ?? this.total ?? this.loaded;\n    const loaded = override?.loaded ?? total;\n    this.emit({\n      stage: \"done\",\n      loaded,\n      total,\n      indeterminate: false,\n      ...(override?.deduped ? { deduped: true as const } : {}),\n    });\n  }\n\n  /** Terminal success for a confirmed dedup: no bytes moved, and none needed to. */\n  finishDeduped(): void {\n    this.finish({ loaded: 0, total: 0, deduped: true });\n  }\n\n  /** Terminal failure, carrying the last known byte counts. */\n  fail(): void {\n    if (this.settled) return;\n    this.settled = true;\n    this.emit({\n      stage: \"error\",\n      loaded: this.loaded,\n      total: this.total,\n      indeterminate: false,\n    });\n  }\n\n  private emit(progress: AttachmentProgress): void {\n    this.lastEmitAt = this.now();\n    this.listener?.(progress);\n  }\n}\n\nexport type ByteProgressHooks = {\n  /** Cumulative bytes handed to the consumer. */\n  onBytes?: (loaded: number) => void;\n  /** The source ended and every byte reached the consumer. */\n  onDone?: () => void;\n  onError?: (error: unknown) => void;\n};\n\n/**\n * Count bytes as a consumer reads them.\n *\n * Uses the manual-reader form rather than `pipeThrough`, whose internal queue\n * reads far ahead of the consumer and would make `loaded` overstate what was\n * actually received. `highWaterMark: 0` is load-bearing for the same reason:\n * at the default of 1 the wrapper pulls one chunk the instant it is\n * constructed, so a caller who never reads still sees bytes counted.\n *\n * `cancel` propagates to the source, which is what keeps reader refcounts\n * (e.g. `KyselyAttachmentStore`'s) correct. Cancelling is an abandonment, not\n * a completion, so it reports `onError` — never `onDone` — carrying the\n * cancel reason the way an `AbortSignal` carries its own, with the DOM's\n * default `AbortError` when the canceller gave none.\n *\n * Returns `source` unchanged when no hook is supplied, so a caller with no\n * listener pays nothing.\n */\nexport function withByteProgress(\n  source: ReadableStream<Uint8Array>,\n  hooks: ByteProgressHooks,\n): ReadableStream<Uint8Array> {\n  if (!hooks.onBytes && !hooks.onDone && !hooks.onError) return source;\n\n  let loaded = 0;\n  let cancelled = false;\n  const reader = source.getReader();\n  return new ReadableStream<Uint8Array>(\n    {\n      async pull(controller) {\n        try {\n          const { done, value } = await reader.read();\n          // A cancel that lands while this read is in flight resolves it as\n          // `done`, and closes the stream. Bailing out here is what stops an\n          // abandoned transfer from reporting completion, and stops the\n          // already-closed controller from throwing a fabricated error into\n          // the catch below.\n          if (cancelled) return;\n          if (done) {\n            hooks.onDone?.();\n            controller.close();\n            return;\n          }\n          loaded += value.byteLength;\n          hooks.onBytes?.(loaded);\n          controller.enqueue(value);\n        } catch (err) {\n          if (cancelled) return;\n          hooks.onError?.(err);\n          controller.error(err);\n        }\n      },\n      cancel(reason) {\n        cancelled = true;\n        reader.cancel(reason).catch(() => {});\n        hooks.onError?.(reason ?? abortError());\n      },\n    },\n    { highWaterMark: 0 },\n  );\n}\n\n/** What an `AbortSignal` carries when `abort()` is called with no reason. */\nfunction abortError(): DOMException {\n  return new DOMException(\"The operation was aborted\", \"AbortError\");\n}\n","import type { AttachmentHash, AttachmentRef } from \"@powerhousedao/reactor\";\nimport {\n  runWithConcurrency,\n  type BatchItemResult,\n  type RunWithConcurrencyOptions,\n} from \"./concurrency.js\";\nimport { AttachmentAlreadyExists } from \"./errors.js\";\nexport type { AttachmentTransferStage } from \"./errors.js\";\nexport {\n  runWithConcurrency,\n  type BatchItemResult,\n  type RunWithConcurrencyOptions,\n} from \"./concurrency.js\";\nimport type { IAttachmentService, IAttachmentUpload } from \"./interfaces.js\";\nimport {\n  ProgressEmitter,\n  withByteProgress,\n  type AttachmentProgress,\n  type AttachmentProgressOptions,\n} from \"./progress.js\";\nimport { createRef } from \"./ref.js\";\nimport { sha256Hex } from \"./replication/hash.js\";\nimport type {\n  AttachmentHeader,\n  AttachmentResponse,\n  AttachmentSendOptions,\n  AttachmentUploadResult,\n  HashFirstReserveAttachmentOptions,\n} from \"./types.js\";\n\nexport { AttachmentService } from \"./attachment-service.js\";\nexport {\n  AttachmentAlreadyExists,\n  AttachmentNotFound,\n  AttachmentPending,\n  AttachmentTransferError,\n  HashMismatch,\n  InvalidAttachmentRef,\n  ReservationNotFound,\n  SizeMismatch,\n  UploadTooLarge,\n} from \"./errors.js\";\nexport type {\n  IAttachmentReader,\n  IAttachmentService,\n  IAttachmentStore,\n  IAttachmentTransport,\n  IAttachmentTransportFactory,\n  IAttachmentUpload,\n  IAttachmentUploadFactory,\n  IReservationStore,\n} from \"./interfaces.js\";\nexport { parseRef, createRef } from \"./ref.js\";\nexport type { ParsedRef } from \"./ref.js\";\nexport type {\n  AttachmentDownloadOptions,\n  AttachmentDownloadTarget,\n  AttachmentDownloadTargetOptions,\n  AttachmentHeader,\n  AttachmentMetadata,\n  AttachmentResponse,\n  AttachmentSendOptions,\n  AttachmentStatOptions,\n  AttachmentStatus,\n  AttachmentTransportConfig,\n  AttachmentUploadResult,\n  AttachmentTargetHeaders,\n  AttachmentUploadTarget,\n  HashFirstReserveAttachmentOptions,\n  UploadFirstReserveAttachmentOptions,\n  Reservation,\n  ReserveAttachmentOptions,\n  TransportFetchResult,\n  TransportResponse,\n} from \"./types.js\";\nexport {\n  parseAttachmentDownloadTarget,\n  parseAttachmentUploadTarget,\n} from \"./targets.js\";\nexport {\n  SwitchboardAttachmentTransport,\n  type SwitchboardTransportConfig,\n  RemoteReservationStore,\n  type SwitchboardClientConfig,\n  RemoteAttachmentUpload,\n  RemoteAttachmentUploadFactory,\n  RemoteAttachmentStore,\n  createRemoteAttachmentService,\n  createFetchUploadTransport,\n  createXhrUploadTransport,\n  type AttachmentUploadRequest,\n  type AttachmentUploadResponse,\n  type AttachmentUploadTransport,\n  type XhrUploadTransportOptions,\n} from \"./switchboard/index.js\";\nexport { NullAttachmentTransport } from \"./null-attachment-transport.js\";\nexport {\n  DEFAULT_PROGRESS_THROTTLE_MS,\n  progressFraction,\n  ProgressEmitter,\n  withByteProgress,\n  type AttachmentProgress,\n  type AttachmentProgressListener,\n  type AttachmentProgressOptions,\n  type AttachmentStage,\n  type ByteProgressHooks,\n  type ProgressEmitterOptions,\n} from \"./progress.js\";\n\nexport type PreprocessResult = {\n  ref: AttachmentRef;\n  hash: AttachmentHash;\n  sizeBytes: number;\n  options: HashFirstReserveAttachmentOptions;\n  data: ReadableStream<Uint8Array>;\n  stream: () => ReadableStream<Uint8Array>;\n};\n\nexport type AttachmentUploadInput = {\n  file: Blob;\n  fileName?: string;\n  mimeType?: string;\n  /** Per-item cancellation, checked between stages. */\n  signal?: AbortSignal;\n};\n\n/**\n * Upload bytes that were already hashed by a separate `preprocess()` call.\n *\n * This is the canonical two-call flow: the ref must reach the document before\n * the bytes are committed, so callers preprocess, dispatch the operation, then\n * upload. Passing the result back in skips the hashing stage rather than\n * faking a zero-millisecond one.\n */\nexport type AttachmentPreprocessedUploadInput = {\n  preprocessed: PreprocessResult;\n  signal?: AbortSignal;\n};\n\n/**\n * Every remote download names the document that authorizes its ref; batches\n * may freely mix documents because the anchor travels with each item.\n */\nexport type AttachmentDownloadInput = {\n  documentId: string;\n  ref: AttachmentRef;\n  signal?: AbortSignal;\n};\n\n/**\n * The document keeps its own name and type for an attachment (the same\n * bytes may appear under different names in different documents), so the\n * blob-producing conveniences let callers override what the server header\n * reports from upload time.\n */\nexport type AttachmentBlobOptions = {\n  mimeType?: string;\n};\n\nexport type AttachmentSaveOptions = {\n  fileName?: string;\n  mimeType?: string;\n};\n\nexport type AttachmentBlobResult = {\n  blob: Blob;\n  header: AttachmentHeader;\n};\n\nexport type AttachmentObjectUrl = {\n  /** Ready for img/iframe/video src. Pins memory until revoke() is called. */\n  url: string;\n  header: AttachmentHeader;\n  revoke: () => void;\n};\n\nexport type AttachmentShareLinkInput = {\n  documentId: string;\n  ref: AttachmentRef;\n  /** Requested link lifetime in seconds; the server clamps to its maximum. */\n  expiresIn?: number;\n  signal?: AbortSignal;\n};\n\n/**\n * A self-contained public URL: anyone holding it can fetch the bytes until\n * expiresAtUtc, with no login and no document access. Minting one requires\n * document read access; once minted it cannot be revoked before expiry.\n */\nexport type AttachmentShareLink = {\n  url: string;\n  expiresAtUtc: string;\n};\n\n/**\n * Batch progress is per item, carrying the item's `index`. There is\n * deliberately no batch-wide byte total: weighting items against each other is\n * a presentation decision the client cannot make, and a confirmed dedup would\n * shrink the denominator mid-flight.\n */\nexport type AttachmentBatchOptions = {\n  /** Bounds preprocessing and transfer together. Defaults to 4. */\n  concurrency?: number;\n  /** Whole-batch cancellation: stops unstarted items. */\n  signal?: AbortSignal;\n  onProgress?: (progress: AttachmentProgress & { index: number }) => void;\n  /**\n   * Fired as each item settles, including items the signal skipped before they\n   * started, so `settled` always reaches `total`.\n   */\n  onItemSettled?: (counts: AttachmentBatchCounts) => void;\n  /** Min ms between byte events, applied per item rather than batch-wide. */\n  throttleMs?: number;\n};\n\nexport type AttachmentBatchCounts = {\n  settled: number;\n  completed: number;\n  failed: number;\n  total: number;\n};\n\nexport const DEFAULT_ATTACHMENT_BATCH_CONCURRENCY = 4;\n\nexport interface IAttachmentClient {\n  preprocess(\n    file: Blob,\n    opts?: { fileName?: string; mimeType?: string },\n  ): Promise<PreprocessResult>;\n  reserve(\n    options: HashFirstReserveAttachmentOptions,\n    send: (handle: IAttachmentUpload) => Promise<AttachmentUploadResult>,\n  ): Promise<AttachmentUploadResult>;\n  /**\n   * Hash, reserve, and transfer one file; a confirmed dedup skips the transfer\n   * and reports a terminal `done` carrying `deduped: true` and zero bytes.\n   *\n   * Also accepts an already-preprocessed payload, so the canonical\n   * preprocess -> dispatch -> upload flow reports progress too.\n   */\n  upload(\n    input: AttachmentUploadInput | AttachmentPreprocessedUploadInput,\n    options?: AttachmentProgressOptions,\n  ): Promise<AttachmentUploadResult>;\n  /**\n   * Document-authorized download of one ref.\n   *\n   * Resolves as soon as the byte stream is available, with `downloading` as\n   * the last event emitted and `loaded: 0`. Byte events and the terminal\n   * `done` arrive as the caller reads the stream — and never arrive at all if\n   * the caller abandons it.\n   */\n  download(\n    input: AttachmentDownloadInput,\n    options?: AttachmentProgressOptions,\n  ): Promise<AttachmentResponse>;\n  /**\n   * Document-authorized download materialized as a typed Blob. The Blob's\n   * type comes from the server header unless overridden — that's what makes\n   * browsers render PDFs inline and images correctly.\n   */\n  downloadBlob(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions & AttachmentProgressOptions,\n  ): Promise<AttachmentBlobResult>;\n  /**\n   * Download and hand the bytes to the browser's save-file flow. Browser\n   * only. fileName defaults to the server header's; pass the document's own\n   * name for per-document naming.\n   */\n  saveAttachment(\n    input: AttachmentDownloadInput,\n    options?: AttachmentSaveOptions & AttachmentProgressOptions,\n  ): Promise<void>;\n  /**\n   * Download and expose the bytes as an object URL for inline rendering\n   * (img/iframe/video src). Callers MUST call revoke() when done — the URL\n   * pins the blob in memory until then.\n   */\n  downloadObjectUrl(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions & AttachmentProgressOptions,\n  ): Promise<AttachmentObjectUrl>;\n  /**\n   * Mint a public share link: a presigned URL anyone can fetch until it\n   * expires, with no login. Authorized exactly like a download (document\n   * read access + the reference index). Requires a presigned-capable\n   * storage backend (S3); rejects when the server answers with an\n   * authenticated switchboard target, which would not be public.\n   */\n  getShareLink(input: AttachmentShareLinkInput): Promise<AttachmentShareLink>;\n  uploadMany(\n    inputs: readonly AttachmentUploadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentUploadResult>[]>;\n  downloadMany(\n    inputs: readonly AttachmentDownloadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentResponse>[]>;\n}\n\n/**\n * Duck-typed dedup detection: bundlers (notably Vite dev pre-bundling) can\n * load two copies of this package's error classes, one for the service and\n * one for the client wrapper, making a plain instanceof check miss the\n * cross-copy throw. Name plus payload shape identifies the error reliably.\n */\nfunction isAttachmentAlreadyExists(\n  err: unknown,\n): err is AttachmentAlreadyExists {\n  if (err instanceof AttachmentAlreadyExists) return true;\n  return (\n    err instanceof Error &&\n    err.name === \"AttachmentAlreadyExists\" &&\n    typeof (err as { hash?: unknown }).hash === \"string\" &&\n    typeof (err as { ref?: unknown }).ref === \"string\"\n  );\n}\n\n// Nothing references the blob yet, so the server header is not readable.\nfunction dedupedHeader(\n  hash: AttachmentHash,\n  options: HashFirstReserveAttachmentOptions,\n): AttachmentHeader {\n  const now = new Date().toISOString();\n  return {\n    hash,\n    mimeType: options.mimeType,\n    fileName: options.fileName,\n    sizeBytes: options.sizeBytes,\n    extension: options.extension ?? null,\n    status: \"available\",\n    source: \"local\",\n    createdAtUtc: now,\n    lastAccessedAtUtc: now,\n    expiresAtUtc: null,\n  };\n}\n\nfunction streamFromBuffer(buf: Uint8Array): ReadableStream<Uint8Array> {\n  return new ReadableStream({\n    start(controller) {\n      controller.enqueue(buf);\n      controller.close();\n    },\n  });\n}\n\n/** Stamps an item's index onto its progress events. */\nfunction itemProgress(\n  options: AttachmentBatchOptions | undefined,\n  index: number,\n): AttachmentProgressOptions | undefined {\n  if (!options?.onProgress && options?.throttleMs === undefined) {\n    return undefined;\n  }\n  return {\n    ...(options.onProgress\n      ? {\n          onProgress: (progress: AttachmentProgress) =>\n            options.onProgress?.({ ...progress, index }),\n        }\n      : {}),\n    ...(options.throttleMs !== undefined\n      ? { throttleMs: options.throttleMs }\n      : {}),\n  };\n}\n\nfunction batchRunOptions<R>(\n  total: number,\n  options: AttachmentBatchOptions | undefined,\n): RunWithConcurrencyOptions<R> {\n  const onItemSettled = options?.onItemSettled;\n  let settled = 0;\n  let completed = 0;\n  let failed = 0;\n  return {\n    concurrency: options?.concurrency ?? DEFAULT_ATTACHMENT_BATCH_CONCURRENCY,\n    ...(options?.signal ? { signal: options.signal } : {}),\n    ...(onItemSettled\n      ? {\n          onSettled: (result: BatchItemResult<R>) => {\n            settled += 1;\n            if (result.status === \"fulfilled\") completed += 1;\n            else failed += 1;\n            onItemSettled({ settled, completed, failed, total });\n          },\n        }\n      : {}),\n  };\n}\n\nclass AttachmentClientImpl implements IAttachmentClient {\n  constructor(private readonly service: IAttachmentService) {}\n\n  async preprocess(\n    file: Blob,\n    opts?: { fileName?: string; mimeType?: string },\n  ): Promise<PreprocessResult> {\n    const buf = await file.arrayBuffer();\n    const bytes = new Uint8Array(buf);\n    const hash = await sha256Hex(bytes);\n    const ref = createRef(hash);\n    const sizeBytes = file.size;\n    const mimeType = opts?.mimeType ?? file.type;\n    const fileName =\n      opts?.fileName ?? (file instanceof File ? file.name : \"attachment\");\n    const options: HashFirstReserveAttachmentOptions = {\n      mimeType,\n      fileName,\n      clientHash: hash,\n      sizeBytes,\n    };\n    const data = streamFromBuffer(bytes);\n    const stream = (): ReadableStream<Uint8Array> => streamFromBuffer(bytes);\n    return { ref, hash, sizeBytes, options, data, stream };\n  }\n\n  /**\n   * Reserve, distinguishing a confirmed dedup from a live upload handle in the\n   * type rather than with a flag: the two outcomes move a different number of\n   * bytes, and every caller has to account for that.\n   */\n  private async reserveOrDedup(\n    options: HashFirstReserveAttachmentOptions,\n  ): Promise<\n    | { kind: \"handle\"; handle: IAttachmentUpload }\n    | { kind: \"deduped\"; result: AttachmentUploadResult }\n  > {\n    try {\n      return { kind: \"handle\", handle: await this.service.reserve(options) };\n    } catch (err) {\n      if (!isAttachmentAlreadyExists(err)) throw err;\n      return {\n        kind: \"deduped\",\n        result: {\n          hash: err.hash,\n          ref: err.ref,\n          header: dedupedHeader(err.hash, options),\n        },\n      };\n    }\n  }\n\n  async reserve(\n    options: HashFirstReserveAttachmentOptions,\n    send: (handle: IAttachmentUpload) => Promise<AttachmentUploadResult>,\n  ): Promise<AttachmentUploadResult> {\n    const outcome = await this.reserveOrDedup(options);\n    if (outcome.kind === \"deduped\") return outcome.result;\n    return send(outcome.handle);\n  }\n\n  async upload(\n    input: AttachmentUploadInput | AttachmentPreprocessedUploadInput,\n    options?: AttachmentProgressOptions,\n  ): Promise<AttachmentUploadResult> {\n    const emitter = new ProgressEmitter(options);\n    const signal = input.signal;\n    try {\n      signal?.throwIfAborted();\n\n      let preprocessed: PreprocessResult;\n      if (\"preprocessed\" in input) {\n        preprocessed = input.preprocessed;\n      } else {\n        // Hashing is genuinely unobservable: preprocess() runs one\n        // crypto.subtle.digest over the whole buffer and WebCrypto has no\n        // streaming digest. The stage is still reported, with a denominator\n        // and indeterminate never cleared, so a UI can name what it waits on.\n        emitter.stage(\"hashing\", { total: input.file.size });\n        preprocessed = await this.preprocess(input.file, {\n          ...(input.fileName !== undefined ? { fileName: input.fileName } : {}),\n          ...(input.mimeType !== undefined ? { mimeType: input.mimeType } : {}),\n        });\n      }\n      const sizeBytes = preprocessed.sizeBytes;\n\n      signal?.throwIfAborted();\n      emitter.stage(\"reserving\");\n      const outcome = await this.reserveOrDedup(preprocessed.options);\n\n      // A confirmed dedup never enters `uploading` — the server already holds\n      // these bytes, so none are sent. Reporting zero of zero keeps the byte\n      // model honest instead of stalling at 0 and then jumping to done.\n      if (outcome.kind === \"deduped\") {\n        emitter.finishDeduped();\n        return outcome.result;\n      }\n\n      signal?.throwIfAborted();\n      emitter.stage(\"uploading\", { total: sizeBytes });\n      // `onProgress` only when someone is listening. The XHR transport keys\n      // its `upload.onprogress` registration off the option being present, and\n      // that registration alone forces a CORS preflight on a presigned PUT —\n      // a cost an unwatched upload must not pay for a callback that would\n      // discard every event anyway.\n      const sendOptions: AttachmentSendOptions = {\n        ...(emitter.active\n          ? {\n              onProgress: (loaded: number, total?: number) =>\n                emitter.bytes(loaded, total ?? sizeBytes),\n            }\n          : {}),\n        ...(signal ? { signal } : {}),\n      };\n      const result = await outcome.handle.send(\n        preprocessed.stream(),\n        sendOptions,\n      );\n      emitter.finish();\n      return result;\n    } catch (err) {\n      emitter.fail();\n      throw err;\n    }\n  }\n\n  /**\n   * The single site where download bytes are instrumented.\n   *\n   * It sits here, above the service, rather than in any store or transport:\n   * one logical get can be several byte streams underneath (an evicted\n   * attachment is fetched from the transport, written to disk, then re-read),\n   * so counting lower down would double-count that path and still miss\n   * local-filesystem reads. Wrapping what `service.get` returns covers the\n   * presigned, switchboard, legacy and local paths by construction, and\n   * `downloadBlob`/`saveAttachment`/`downloadObjectUrl` inherit it.\n   */\n  private async getWithProgress(\n    input: AttachmentDownloadInput,\n    emitter: ProgressEmitter,\n  ): Promise<AttachmentResponse> {\n    const { header, body } = await this.service.get(input.ref, {\n      documentId: input.documentId,\n      signal: input.signal,\n    });\n    emitter.stage(\"downloading\", { total: header.sizeBytes });\n    if (!emitter.active) return { header, body };\n    return {\n      header,\n      body: withByteProgress(body, {\n        onBytes: (loaded) => emitter.bytes(loaded),\n        onDone: () => emitter.finish(),\n        onError: () => emitter.fail(),\n      }),\n    };\n  }\n\n  async download(\n    input: AttachmentDownloadInput,\n    options?: AttachmentProgressOptions,\n  ): Promise<AttachmentResponse> {\n    const emitter = new ProgressEmitter(options);\n    try {\n      input.signal?.throwIfAborted();\n      emitter.stage(\"requesting-download-target\");\n      return await this.getWithProgress(input, emitter);\n    } catch (err) {\n      emitter.fail();\n      throw err;\n    }\n  }\n\n  async downloadBlob(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions & AttachmentProgressOptions,\n  ): Promise<AttachmentBlobResult> {\n    const emitter = new ProgressEmitter(options);\n    try {\n      input.signal?.throwIfAborted();\n      emitter.stage(\"requesting-download-target\");\n      const { header, body } = await this.getWithProgress(input, emitter);\n      const reader = body.getReader();\n      const chunks: BlobPart[] = [];\n      for (;;) {\n        const { done, value } = await reader.read();\n        if (done) break;\n        chunks.push(value as BlobPart);\n      }\n      const blob = new Blob(chunks, {\n        type: options?.mimeType ?? header.mimeType,\n      });\n      // Draining the stream already finished the emitter; latching makes this\n      // a no-op there, and a guarantee for any body that closes without one.\n      emitter.finish();\n      return { blob, header };\n    } catch (err) {\n      emitter.fail();\n      throw err;\n    }\n  }\n\n  async saveAttachment(\n    input: AttachmentDownloadInput,\n    options?: AttachmentSaveOptions & AttachmentProgressOptions,\n  ): Promise<void> {\n    if (typeof document === \"undefined\") {\n      throw new Error(\n        \"saveAttachment requires a browser environment; use downloadBlob elsewhere\",\n      );\n    }\n    const { blob, header } = await this.downloadBlob(input, options);\n    const url = URL.createObjectURL(blob);\n    try {\n      const anchor = document.createElement(\"a\");\n      anchor.href = url;\n      anchor.download = options?.fileName ?? header.fileName;\n      anchor.click();\n    } finally {\n      URL.revokeObjectURL(url);\n    }\n  }\n\n  async downloadObjectUrl(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions & AttachmentProgressOptions,\n  ): Promise<AttachmentObjectUrl> {\n    const { blob, header } = await this.downloadBlob(input, options);\n    const url = URL.createObjectURL(blob);\n    let revoked = false;\n    return {\n      url,\n      header,\n      revoke: () => {\n        if (revoked) return;\n        revoked = true;\n        URL.revokeObjectURL(url);\n      },\n    };\n  }\n\n  async getShareLink(\n    input: AttachmentShareLinkInput,\n  ): Promise<AttachmentShareLink> {\n    input.signal?.throwIfAborted();\n    const target = await this.service.getDownloadTarget(input.ref, {\n      documentId: input.documentId,\n      ...(input.expiresIn !== undefined ? { expiresIn: input.expiresIn } : {}),\n      ...(input.signal !== undefined ? { signal: input.signal } : {}),\n    });\n    if (target.kind !== \"presigned-get\") {\n      throw new Error(\n        \"Public share links require a presigned-capable storage backend (S3); this server answered with an authenticated target\",\n      );\n    }\n    return { url: target.url, expiresAtUtc: target.expiresAtUtc };\n  }\n\n  uploadMany(\n    inputs: readonly AttachmentUploadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentUploadResult>[]> {\n    return runWithConcurrency(\n      inputs,\n      (input, index) => this.upload(input, itemProgress(options, index)),\n      batchRunOptions(inputs.length, options),\n    );\n  }\n\n  /**\n   * `concurrency` bounds download-target negotiation, not simultaneous byte\n   * transfer: each item resolves when its stream is handed over, and the bytes\n   * move only as the caller reads. Byte progress makes that pre-existing\n   * behavior visible; it does not change it.\n   */\n  downloadMany(\n    inputs: readonly AttachmentDownloadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentResponse>[]> {\n    return runWithConcurrency(\n      inputs,\n      (input, index) => this.download(input, itemProgress(options, index)),\n      batchRunOptions(inputs.length, options),\n    );\n  }\n}\n\nexport function createAttachmentClient(\n  service: IAttachmentService,\n): IAttachmentClient {\n  return new AttachmentClientImpl(service);\n}\n"],"mappings":"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"}

package/dist/hash-CKHeI4AH.js

@@ -0,0 +1,26 @@
+//#region src/replication/hash.ts
+/**
+* Lowercase SHA-256 hex of `bytes` -- the `attachment://v1:` hash format
+* (`packages/reactor/src/attachments/types.ts`).
+*
+* WebCrypto, so the same code runs in Node and in a browser realm. There is no
+* streaming digest in WebCrypto, which is why verification happens over
+* collected bytes.
+*/
+async function sha256Hex(bytes) {
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", digestable(bytes));
+	return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** WebCrypto refuses a SharedArrayBuffer-backed view, so only that one is copied. */
+function digestable(bytes) {
+	if (typeof SharedArrayBuffer !== "undefined" && bytes.buffer instanceof SharedArrayBuffer) {
+		const copy = new Uint8Array(bytes.byteLength);
+		copy.set(bytes);
+		return copy;
+	}
+	return bytes;
+}
+//#endregion
+export { sha256Hex as t };
+
+//# sourceMappingURL=hash-CKHeI4AH.js.map

package/dist/hash-CKHeI4AH.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-CKHeI4AH.js","names":[],"sources":["../src/replication/hash.ts"],"sourcesContent":["import type { AttachmentHash } from \"@powerhousedao/reactor\";\n\n/**\n * Lowercase SHA-256 hex of `bytes` -- the `attachment://v1:` hash format\n * (`packages/reactor/src/attachments/types.ts`).\n *\n * WebCrypto, so the same code runs in Node and in a browser realm. There is no\n * streaming digest in WebCrypto, which is why verification happens over\n * collected bytes.\n */\nexport async function sha256Hex(bytes: Uint8Array): Promise<AttachmentHash> {\n  const digest = await globalThis.crypto.subtle.digest(\n    \"SHA-256\",\n    digestable(bytes),\n  );\n  return Array.from(new Uint8Array(digest))\n    .map((byte) => byte.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n}\n\n/** WebCrypto refuses a SharedArrayBuffer-backed view, so only that one is copied. */\nfunction digestable(bytes: Uint8Array): Uint8Array<ArrayBuffer> {\n  if (\n    typeof SharedArrayBuffer !== \"undefined\" &&\n    bytes.buffer instanceof SharedArrayBuffer\n  ) {\n    const copy = new Uint8Array(bytes.byteLength);\n    copy.set(bytes);\n    return copy;\n  }\n  return bytes as Uint8Array<ArrayBuffer>;\n}\n"],"mappings":";;;;;;;;;AAUA,eAAsB,UAAU,OAA4C;CAC1E,MAAM,SAAS,MAAM,WAAW,OAAO,OAAO,OAC5C,WACA,WAAW,KAAK,CAClB;CACA,OAAO,MAAM,KAAK,IAAI,WAAW,MAAM,CAAC,CAAC,CACtC,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CACjD,KAAK,EAAE;AACZ;;AAGA,SAAS,WAAW,OAA4C;CAC9D,IACE,OAAO,sBAAsB,eAC7B,MAAM,kBAAkB,mBACxB;EACA,MAAM,OAAO,IAAI,WAAW,MAAM,UAAU;EAC5C,KAAK,IAAI,KAAK;EACd,OAAO;CACT;CACA,OAAO;AACT"}

package/dist/index.d.ts

@@ -1,9 +1,24 @@
-import { $ as AttachmentPending, A as IReservationStore, B as AttachmentStatus, C as IAttachmentReader, D as IAttachmentTransportFactory, E as IAttachmentTransport, G as HashFirstReserveAttachmentOptions, H as AttachmentTransportConfig, I as AttachmentHeader, J as TransportFetchResult, K as Reservation, L as AttachmentMetadata, M as AttachmentBackendKind, N as AttachmentDownloadOptions, O as IAttachmentUpload, P as AttachmentDownloadTarget, Q as AttachmentNotFound, R as AttachmentResponse, S as IAttachmentBackend, T as IAttachmentStore, U as AttachmentUploadResult, V as AttachmentTargetHeaders, W as AttachmentUploadTarget, X as UploadFirstReserveAttachmentOptions, Y as TransportResponse, Z as AttachmentAlreadyExists, _ as createRef, a as RemoteAttachmentUpload, at as SizeMismatch, b as parseAttachmentDownloadTarget, c as XhrUploadTransportOptions, d as AttachmentUploadResponse, et as AttachmentTransferError, f as AttachmentUploadTransport, g as ParsedRef, h as SwitchboardTransportConfig, i as RemoteAttachmentUploadFactory, it as ReservationNotFound, j as AttachmentBackendHealth, k as IAttachmentUploadFactory, l as createXhrUploadTransport, m as SwitchboardAttachmentTransport, n as createRemoteAttachmentService, nt as HashMismatch, o as RemoteReservationStore, ot as UploadTooLarge, p as createFetchUploadTransport, q as ReserveAttachmentOptions, r as RemoteAttachmentStore, rt as InvalidAttachmentRef, s as SwitchboardClientConfig, t as NullAttachmentTransport, tt as AttachmentTransferStage, u as AttachmentUploadRequest, v as parseRef, w as IAttachmentService, x as parseAttachmentUploadTarget, y as AttachmentService, z as AttachmentSendOptions } from "./null-attachment-transport-CMrO_ZKA.js";
-import * as kysely from "kysely";
-import { Kysely, Transaction } from "kysely";
+import { A as InvalidAttachmentRef, C as AttachmentMetadataField, D as AttachmentTransferStage, E as AttachmentTransferError, M as SizeMismatch, N as UploadTooLarge, O as HashMismatch, S as AttachmentAlreadyExists, T as AttachmentPending, _ as createRef, a as RemoteAttachmentUpload, b as parseAttachmentDownloadTarget, c as XhrUploadTransportOptions, d as AttachmentUploadResponse, f as AttachmentUploadTransport, g as ParsedRef, h as SwitchboardTransportConfig, i as RemoteAttachmentUploadFactory, j as ReservationNotFound, k as InvalidAttachmentMetadata, l as createXhrUploadTransport, m as SwitchboardAttachmentTransport, n as createRemoteAttachmentService, o as RemoteReservationStore, p as createFetchUploadTransport, r as RemoteAttachmentStore, s as SwitchboardClientConfig, t as NullAttachmentTransport, u as AttachmentUploadRequest, v as parseRef, w as AttachmentNotFound, x as parseAttachmentUploadTarget, y as AttachmentService } from "./null-attachment-transport-dg7vi6F4.js";
+import { A as UploadFirstReserveAttachmentOptions, C as AttachmentUploadResult, D as ReserveAttachmentOptions, E as Reservation, O as TransportFetchResult, S as AttachmentTransportConfig, T as HashFirstReserveAttachmentOptions, _ as AttachmentResponse, a as IAttachmentTransport, b as AttachmentStatus, c as IAttachmentUploadFactory, d as AttachmentBackendKind, f as AttachmentDownloadOptions, g as AttachmentMetadata, h as AttachmentHeader, i as IAttachmentStore, k as TransportResponse, l as IReservationStore, m as AttachmentDownloadTargetOptions, n as IAttachmentReader, o as IAttachmentTransportFactory, p as AttachmentDownloadTarget, r as IAttachmentService, s as IAttachmentUpload, t as IAttachmentBackend, u as AttachmentBackendHealth, v as AttachmentSendOptions, w as AttachmentUploadTarget, x as AttachmentTargetHeaders, y as AttachmentStatOptions } from "./interfaces-jHW9JXv1.js";
+import { a as IAttachmentReferenceScanner, c as IAttachmentSchemaCompiler, i as IAttachmentReferenceReader, n as AttachmentReferencePageResult, o as IAttachmentReferenceWriter, s as CompiledAttachmentExtractor, t as AttachmentReferenceInput } from "./types-AagIcjTD.js";
+import { Kysely } from "kysely";
 import { AttachmentHash, AttachmentRef, BaseReadModel, DocumentViewDatabase, IConsistencyTracker, IDocumentModelRegistry, IOperationIndex, IWriteCache } from "@powerhousedao/reactor";
-import { Action, DocumentModelModule, OperationWithContext } from "@powerhousedao/shared/document-model";
-
+import { DocumentModelModule, OperationWithContext } from "@powerhousedao/shared/document-model";
+//#region src/reserve-metadata.d.ts
+/** The descriptive fields of a reservation, as a caller supplies them. */
+type ReserveMetadata = {
+  mimeType: string;
+  fileName: string;
+  extension?: string | null;
+};
+/**
+ * Validates reserve metadata with the rules the switchboard reserve route
+ * applies.
+ *
+ * @throws InvalidAttachmentMetadata naming the first field that fails.
+ */
+export declare function validateReserveMetadata(meta: ReserveMetadata): void;
+//#endregion
 //#region src/storage/kysely/types.d.ts
 interface AttachmentTable {
   hash: string;
@@ -34,7 +49,7 @@ interface AttachmentDatabase {
 }
 //#endregion
 //#region src/storage/kysely/attachment-store.d.ts
-declare class KyselyAttachmentStore implements IAttachmentStore {
+export declare class KyselyAttachmentStore implements IAttachmentStore {
   private readonly db;
   private readonly transport;
   private readonly basePath;
@@ -42,10 +57,11 @@ declare class KyselyAttachmentStore implements IAttachmentStore {
   constructor(db: Kysely<AttachmentDatabase>, transport: IAttachmentTransport, basePath: string);
   stat(hash: AttachmentHash): Promise<AttachmentHeader>;
   has(hash: AttachmentHash): Promise<boolean>;
-  get(hash: AttachmentHash, signal?: AbortSignal): Promise<AttachmentResponse>;
+  get(hash: AttachmentHash, signal?: AbortSignal, documentId?: string): Promise<AttachmentResponse>;
   put(hash: AttachmentHash, metadata: AttachmentMetadata, data: ReadableStream<Uint8Array>): Promise<void>;
   evict(hash: AttachmentHash): Promise<void>;
   storageUsed(): Promise<number>;
+  private fetchRemote;
   private findPendingReservation;
   private acquireReader;
   private releaseReader;
@@ -53,8 +69,8 @@ declare class KyselyAttachmentStore implements IAttachmentStore {
 }
 //#endregion
 //#region src/storage/kysely/reservation-store.d.ts
-declare const DEFAULT_RESERVATION_TTL_MS: number;
-declare class KyselyReservationStore implements IReservationStore {
+export declare const DEFAULT_RESERVATION_TTL_MS: number;
+export declare class KyselyReservationStore implements IReservationStore {
   private readonly db;
   private readonly ttlMs;
   constructor(db: Kysely<AttachmentDatabase>, ttlMs?: number);
@@ -65,16 +81,16 @@ declare class KyselyReservationStore implements IReservationStore {
 }
 //#endregion
 //#region src/storage/migrations/migrator.d.ts
-declare const ATTACHMENT_SCHEMA = "attachments";
+export declare const ATTACHMENT_SCHEMA = "attachments";
 interface MigrationResult {
   success: boolean;
   migrationsExecuted: string[];
   error?: Error;
 }
-declare function runAttachmentMigrations(db: Kysely<any>, schema?: string): Promise<MigrationResult>;
+export declare function runAttachmentMigrations(db: Kysely<any>, schema?: string): Promise<MigrationResult>;
 //#endregion
 //#region src/direct/direct-attachment-upload.d.ts
-declare class DirectAttachmentUpload implements IAttachmentUpload {
+export declare class DirectAttachmentUpload implements IAttachmentUpload {
   private readonly reservation;
   private readonly db;
   private readonly basePath;
@@ -88,7 +104,7 @@ declare class DirectAttachmentUpload implements IAttachmentUpload {
 }
 //#endregion
 //#region src/direct/direct-attachment-upload-factory.d.ts
-declare class DirectAttachmentUploadFactory implements IAttachmentUploadFactory {
+export declare class DirectAttachmentUploadFactory implements IAttachmentUploadFactory {
   private readonly db;
   private readonly basePath;
   private readonly reservations;
@@ -108,7 +124,7 @@ type FilesystemAttachmentBackendConfig = {
  * at the server edge, while this adapter validates that a filesystem backend
  * can never accidentally return a direct-provider target.
  */
-declare class FilesystemAttachmentBackend implements IAttachmentBackend {
+export declare class FilesystemAttachmentBackend implements IAttachmentBackend {
   private readonly store;
   private readonly config;
   readonly kind: "filesystem";
@@ -124,11 +140,13 @@ type AttachmentBuildResult = {
   service: AttachmentService;
   store: KyselyAttachmentStore;
   reservations: KyselyReservationStore;
-  uploadFactory: IAttachmentUploadFactory; /** Selected direct-transfer backend, when startup configured one. */
-  backend?: IAttachmentBackend; /** Stops the reservation sweep timer, if one was configured via withReservationSweepMs(). */
+  uploadFactory: IAttachmentUploadFactory;
+  /** Selected direct-transfer backend, when startup configured one. */
+  backend?: IAttachmentBackend;
+  /** Stops the reservation sweep timer, if one was configured via withReservationSweepMs(). */
   destroy: () => void;
 };
-declare class AttachmentBuilder {
+export declare class AttachmentBuilder {
   private readonly db;
   private readonly storagePath;
   private transport;
@@ -153,98 +171,40 @@ declare class AttachmentBuilder {
   build(): Promise<AttachmentBuildResult>;
 }
 //#endregion
-//#region src/reference-index/types.d.ts
-interface CompiledAttachmentExtractor {
-  extract(action: Action): AttachmentRef[];
-}
-interface IAttachmentSchemaCompiler {
-  forModuleAction(module: DocumentModelModule, actionType: string): CompiledAttachmentExtractor;
-}
-//#endregion
 //#region src/reference-index/attachment-schema-compiler.d.ts
-declare class AttachmentSchemaCompiler implements IAttachmentSchemaCompiler {
+export declare class AttachmentSchemaCompiler implements IAttachmentSchemaCompiler {
   private readonly cache;
   forModuleAction(module: DocumentModelModule, actionType: string): CompiledAttachmentExtractor;
 }
 //#endregion
-//#region src/read-models/attachment-reference/types.d.ts
-interface AttachmentReferenceInput {
-  documentId: string;
-  ref: AttachmentRef;
-  operationId: string;
-  branch: string;
-  scope: string;
-  ordinal: number;
-}
-interface IAttachmentReferenceReader {
-  hasReference(documentId: string, ref: AttachmentRef): Promise<boolean>;
-}
-interface IAttachmentReferenceWriter {
-  addReferences(references: readonly AttachmentReferenceInput[]): Promise<void>;
-}
-//#endregion
 //#region src/read-models/attachment-reference/index-builder.d.ts
 type AttachmentReferenceIndexBuildResult = {
   store: IAttachmentReferenceReader & IAttachmentReferenceWriter;
 };
-declare class AttachmentReferenceIndexBuilder {
+export declare class AttachmentReferenceIndexBuilder {
   private readonly db;
   constructor(db: Kysely<unknown>);
   build(): Promise<AttachmentReferenceIndexBuildResult>;
 }
 //#endregion
 //#region src/read-models/attachment-reference/attachment-reference-read-model.d.ts
-declare const ATTACHMENT_REFERENCE_READ_MODEL_ID = "attachment-reference-read-model";
-declare class AttachmentReferenceReadModel extends BaseReadModel {
+export declare const ATTACHMENT_REFERENCE_READ_MODEL_ID = "attachment-reference-read-model";
+/**
+ * Indexes attachment references in chunks.
+ *
+ * Each reference row stands on its own and is written insert-or-do-nothing, so
+ * a batch that commits in pieces exposes no partial structure, and re-indexing
+ * the same range writes nothing new: the catch-up sweep needs no stream suffix.
+ *
+ * The rows live on another handle, so the purge fence is "skip": a tombstoned
+ * id's operations are dropped at commit and its marker deletes its rows.
+ */
+export declare class AttachmentReferenceReadModel extends BaseReadModel {
   private readonly documentModelRegistry;
   private readonly schemaCompiler;
   private readonly referenceWriter;
-  private indexingQueue;
-  private checkpointTarget;
-  /**
-   * How far a replay may skip ahead of the cursor: the highest ordinal already
-   * pulled from the index while the cursor was parked.
-   *
-   * NOT a claim that every ordinal below it committed -- the parked ordinal is
-   * precisely the one that did not -- so it is a hint, and {@link replayFrom}
-   * re-probes the gap before honouring it.
-   */
-  private replayedThrough;
-  private warnedCheckpoint;
   constructor(db: Kysely<DocumentViewDatabase>, operationIndex: IOperationIndex, writeCache: IWriteCache, consistencyTracker: IConsistencyTracker, documentModelRegistry: IDocumentModelRegistry, schemaCompiler: IAttachmentSchemaCompiler, referenceWriter: IAttachmentReferenceWriter);
-  indexOperations(items: OperationWithContext[]): Promise<void>;
-  init(): Promise<void>;
-  private enqueue;
   protected commitOperations(items: OperationWithContext[]): Promise<void>;
-  private indexOperationsInOrdinalOrder;
-  /**
-   * Writes the cursor parked by indexOperationsInOrdinalOrder instead of the
-   * batch maximum, so indexing an operation above a gap never advances past it.
-   */
-  protected saveState(trx: Transaction<DocumentViewDatabase>, items: OperationWithContext[]): Promise<void>;
-  /** Last ordinal of the contiguous run starting at lastOrdinal + 1. */
-  private contiguousEnd;
-  /**
-   * Opens a replay at the lowest ordinal still worth reading.
-   *
-   * {@link replayedThrough} is what keeps a permanently held hole -- a
-   * rolled-back insert, which never fills -- from re-reading the whole tail on
-   * every batch. It cannot be trusted on its own: a hole that fills without
-   * being delivered here is visible only in the index, and a mark that is
-   * never questioned would hide that operation for the life of the process.
-   * That happens whenever another writer commits the gap (a second reactor on
-   * the same database), and it leaves the cursor parked below an operation
-   * whose references were never written -- `hasReference` then answers false
-   * for an attachment that is genuinely referenced.
-   *
-   * So a parked batch spends one page probing the gap: the first row above the
-   * cursor is the missing ordinal itself once it commits. Finding it drops the
-   * mark and replays from the cursor; not finding it leaves the mark standing,
-   * which is the cheap path and the common one.
-   */
-  private replayFrom;
-  private loadThroughOrdinal;
-  private sortAndDedupe;
 }
 //#endregion
 //#region src/read-models/attachment-reference/storage/types.d.ts
@@ -263,31 +223,40 @@ interface AttachmentReferenceDatabase {
 }
 //#endregion
 //#region src/read-models/attachment-reference/kysely-attachment-reference-store.d.ts
-declare class KyselyAttachmentReferenceStore implements IAttachmentReferenceReader, IAttachmentReferenceWriter {
+export declare class KyselyAttachmentReferenceStore implements IAttachmentReferenceReader, IAttachmentReferenceScanner, IAttachmentReferenceWriter {
   private readonly db;
   constructor(db: Kysely<AttachmentReferenceDatabase>);
   hasReference(documentId: string, ref: AttachmentRef): Promise<boolean>;
+  referencingScopes(documentId: string, ref: AttachmentRef): Promise<string[]>;
+  /**
+   * Keyset paging over the unique `(document_id, attachment_ref)` constraint,
+   * rather than OFFSET: a scan that runs while the read model is still
+   * indexing must not skip or repeat a row because rows appeared behind the
+   * cursor. That is exactly the boot case the replicator's re-scan runs in.
+   */
+  listReferences(cursor: string | undefined, limit: number): Promise<AttachmentReferencePageResult>;
   addReferences(references: readonly AttachmentReferenceInput[]): Promise<void>;
+  removeDocuments(documentIds: readonly string[]): Promise<void>;
 }
 //#endregion
 //#region src/read-models/attachment-reference/storage/migrations/migrator.d.ts
-declare const ATTACHMENT_REFERENCE_SCHEMA = "attachment_reference_read_model";
-declare const ATTACHMENT_REFERENCE_MIGRATION_TABLE = "kysely_migration_attachment_reference_read_model";
-declare const ATTACHMENT_REFERENCE_MIGRATION_LOCK_TABLE = "kysely_migration_attachment_reference_read_model_lock";
+export declare const ATTACHMENT_REFERENCE_SCHEMA = "attachment_reference_read_model";
+export declare const ATTACHMENT_REFERENCE_MIGRATION_TABLE = "kysely_migration_attachment_reference_read_model";
+export declare const ATTACHMENT_REFERENCE_MIGRATION_LOCK_TABLE = "kysely_migration_attachment_reference_read_model_lock";
 interface AttachmentReferenceMigrationResult {
   success: boolean;
   migrationsExecuted: string[];
   error?: Error;
 }
-declare function runAttachmentReferenceMigrations(db: Kysely<unknown>, schema?: string): Promise<AttachmentReferenceMigrationResult>;
-declare function rollbackAttachmentReferenceMigration(db: Kysely<unknown>, schema?: string): Promise<AttachmentReferenceMigrationResult>;
-declare function getAttachmentReferenceMigrationStatus(db: Kysely<unknown>, schema?: string): Promise<readonly kysely.MigrationInfo[]>;
+export declare function runAttachmentReferenceMigrations(db: Kysely<unknown>, schema?: string): Promise<AttachmentReferenceMigrationResult>;
+export declare function rollbackAttachmentReferenceMigration(db: Kysely<unknown>, schema?: string): Promise<AttachmentReferenceMigrationResult>;
+export declare function getAttachmentReferenceMigrationStatus(db: Kysely<unknown>, schema?: string): Promise<readonly import("kysely").MigrationInfo[]>;
 //#endregion
 //#region src/storage/s3/config.d.ts
-declare const DEFAULT_S3_ATTACHMENT_PREFIX = "attachments";
-declare const DEFAULT_S3_UPLOAD_TTL_SECONDS = 900;
-declare const DEFAULT_S3_DOWNLOAD_TTL_SECONDS = 300;
-declare const MAX_S3_PRESIGN_TTL_SECONDS = 604800;
+export declare const DEFAULT_S3_ATTACHMENT_PREFIX = "attachments";
+export declare const DEFAULT_S3_UPLOAD_TTL_SECONDS = 900;
+export declare const DEFAULT_S3_DOWNLOAD_TTL_SECONDS = 300;
+export declare const MAX_S3_PRESIGN_TTL_SECONDS = 604800;
 type S3AttachmentConfig = {
   endpoint: string;
   region: string;
@@ -306,12 +275,12 @@ type AttachmentStorageConfig = {
   s3: S3AttachmentConfig;
 };
 type Environment = Readonly<Record<string, string | undefined>>;
-declare function normalizeS3AttachmentPrefix(prefix: string): string;
-declare function parseAttachmentStorageConfig(env?: Environment): AttachmentStorageConfig;
+export declare function normalizeS3AttachmentPrefix(prefix: string): string;
+export declare function parseAttachmentStorageConfig(env?: Environment): AttachmentStorageConfig;
 //#endregion
 //#region src/storage/s3/keying.d.ts
-declare function deriveS3AttachmentKey(hash: string, prefix: string): string;
-declare function sha256HexToBase64(hash: string): string;
+export declare function deriveS3AttachmentKey(hash: string, prefix: string): string;
+export declare function sha256HexToBase64(hash: string): string;
 //#endregion
 //#region src/storage/s3/primitives.d.ts
 interface S3CommandClient {
@@ -323,7 +292,7 @@ type Dependencies = {
   presign?: S3Presigner;
   now?: () => Date;
 };
-declare class S3AttachmentPrimitives {
+export declare class S3AttachmentPrimitives {
   readonly config: S3AttachmentConfig;
   readonly client: S3CommandClient;
   readonly presign: S3Presigner;
@@ -336,7 +305,7 @@ declare class S3AttachmentPrimitives {
   createUploadTarget(hash: string, mimeType: string, ttlSeconds?: number): Promise<AttachmentUploadTarget>;
   createDownloadTarget(hash: string, ttlSeconds?: number): Promise<AttachmentDownloadTarget>;
 }
-declare function createS3AttachmentPrimitives(config: S3AttachmentConfig, dependencies?: Dependencies): S3AttachmentPrimitives;
+export declare function createS3AttachmentPrimitives(config: S3AttachmentConfig, dependencies?: Dependencies): S3AttachmentPrimitives;
 //#endregion
 //#region src/storage/s3/backend.d.ts
 type S3AttachmentBackendDependencies = {
@@ -347,7 +316,7 @@ type S3AttachmentBackendDependencies = {
   downloadTtlSeconds?: number;
 };
 /** Server-only S3 capability. Callers complete authorization before download. */
-declare class S3AttachmentBackend implements IAttachmentBackend {
+export declare class S3AttachmentBackend implements IAttachmentBackend {
   private readonly db;
   readonly config: S3AttachmentConfig;
   readonly kind: "s3";
@@ -361,12 +330,13 @@ declare class S3AttachmentBackend implements IAttachmentBackend {
   exists(hash: AttachmentHash): Promise<boolean>;
   health(): Promise<AttachmentBackendHealth>;
 }
-declare function createS3AttachmentBackend(db: Kysely<AttachmentDatabase>, config: S3AttachmentConfig, dependencies?: S3AttachmentBackendDependencies): S3AttachmentBackend;
+export declare function createS3AttachmentBackend(db: Kysely<AttachmentDatabase>, config: S3AttachmentConfig, dependencies?: S3AttachmentBackendDependencies): S3AttachmentBackend;
 //#endregion
 //#region src/storage/s3/upload-factory.d.ts
-declare class S3AttachmentUploadFactory implements IAttachmentUploadFactory {
+export declare class S3AttachmentUploadFactory implements IAttachmentUploadFactory {
   createUpload(reservation: Reservation): IAttachmentUpload;
 }
 //#endregion
-export { ATTACHMENT_REFERENCE_MIGRATION_LOCK_TABLE, ATTACHMENT_REFERENCE_MIGRATION_TABLE, ATTACHMENT_REFERENCE_READ_MODEL_ID, ATTACHMENT_REFERENCE_SCHEMA, ATTACHMENT_SCHEMA, AttachmentAlreadyExists, type AttachmentBackendHealth, type AttachmentBackendKind, type AttachmentBuildResult, AttachmentBuilder, type AttachmentDatabase, type AttachmentDownloadOptions, type AttachmentDownloadTarget, type AttachmentHeader, type AttachmentMetadata, AttachmentNotFound, AttachmentPending, type AttachmentReferenceIndexBuildResult, AttachmentReferenceIndexBuilder, type AttachmentReferenceInput, type AttachmentReferenceMigrationResult, AttachmentReferenceReadModel, type AttachmentResponse, AttachmentSchemaCompiler, type AttachmentSendOptions, AttachmentService, type AttachmentStatus, type AttachmentStorageConfig, type AttachmentTargetHeaders, AttachmentTransferError, type AttachmentTransferStage, type AttachmentTransportConfig, type AttachmentUploadRequest, type AttachmentUploadResponse, type AttachmentUploadResult, type AttachmentUploadTarget, type AttachmentUploadTransport, type CompiledAttachmentExtractor, DEFAULT_RESERVATION_TTL_MS, DEFAULT_S3_ATTACHMENT_PREFIX, DEFAULT_S3_DOWNLOAD_TTL_SECONDS, DEFAULT_S3_UPLOAD_TTL_SECONDS, DirectAttachmentUpload, DirectAttachmentUploadFactory, FilesystemAttachmentBackend, type FilesystemAttachmentBackendConfig, type HashFirstReserveAttachmentOptions, HashMismatch, type IAttachmentBackend, type IAttachmentReader, type IAttachmentReferenceReader, type IAttachmentReferenceWriter, type IAttachmentSchemaCompiler, type IAttachmentService, type IAttachmentStore, type IAttachmentTransport, type IAttachmentTransportFactory, type IAttachmentUpload, type IAttachmentUploadFactory, type IReservationStore, InvalidAttachmentRef, KyselyAttachmentReferenceStore, KyselyAttachmentStore, KyselyReservationStore, MAX_S3_PRESIGN_TTL_SECONDS, NullAttachmentTransport, type ParsedRef, RemoteAttachmentStore, RemoteAttachmentUpload, RemoteAttachmentUploadFactory, RemoteReservationStore, type Reservation, ReservationNotFound, type ReserveAttachmentOptions, S3AttachmentBackend, type S3AttachmentBackendDependencies, type S3AttachmentConfig, S3AttachmentPrimitives, S3AttachmentUploadFactory, type S3CommandClient, type S3Presigner, SizeMismatch, SwitchboardAttachmentTransport, type SwitchboardClientConfig, type SwitchboardTransportConfig, type TransportFetchResult, type TransportResponse, type UploadFirstReserveAttachmentOptions, UploadTooLarge, type XhrUploadTransportOptions, createFetchUploadTransport, createRef, createRemoteAttachmentService, createS3AttachmentBackend, createS3AttachmentPrimitives, createXhrUploadTransport, deriveS3AttachmentKey, getAttachmentReferenceMigrationStatus, normalizeS3AttachmentPrefix, parseAttachmentDownloadTarget, parseAttachmentStorageConfig, parseAttachmentUploadTarget, parseRef, rollbackAttachmentReferenceMigration, runAttachmentMigrations, runAttachmentReferenceMigrations, sha256HexToBase64 };
+export { AttachmentAlreadyExists, type AttachmentBackendHealth, type AttachmentBackendKind, type AttachmentBuildResult, type AttachmentDatabase, type AttachmentDownloadOptions, type AttachmentDownloadTarget, type AttachmentDownloadTargetOptions, type AttachmentHeader, type AttachmentMetadata, type AttachmentMetadataField, AttachmentNotFound, AttachmentPending, type AttachmentReferenceIndexBuildResult, type AttachmentReferenceInput, type AttachmentReferenceMigrationResult, type AttachmentResponse, type AttachmentSendOptions, AttachmentService, type AttachmentStatOptions, type AttachmentStatus, type AttachmentStorageConfig, type AttachmentTargetHeaders, AttachmentTransferError, type AttachmentTransferStage, type AttachmentTransportConfig, type AttachmentUploadRequest, type AttachmentUploadResponse, type AttachmentUploadResult, type AttachmentUploadTarget, type AttachmentUploadTransport, type CompiledAttachmentExtractor, type FilesystemAttachmentBackendConfig, type HashFirstReserveAttachmentOptions, HashMismatch, type IAttachmentBackend, type IAttachmentReader, type IAttachmentReferenceReader, type IAttachmentReferenceWriter, type IAttachmentSchemaCompiler, type IAttachmentService, type IAttachmentStore, type IAttachmentTransport, type IAttachmentTransportFactory, type IAttachmentUpload, type IAttachmentUploadFactory, type IReservationStore, InvalidAttachmentMetadata, InvalidAttachmentRef, NullAttachmentTransport, type ParsedRef, RemoteAttachmentStore, RemoteAttachmentUpload, RemoteAttachmentUploadFactory, RemoteReservationStore, type Reservation, ReservationNotFound, type ReserveAttachmentOptions, type ReserveMetadata, type S3AttachmentBackendDependencies, type S3AttachmentConfig, type S3CommandClient, type S3Presigner, SizeMismatch, SwitchboardAttachmentTransport, type SwitchboardClientConfig, type SwitchboardTransportConfig, type TransportFetchResult, type TransportResponse, type UploadFirstReserveAttachmentOptions, UploadTooLarge, type XhrUploadTransportOptions, createFetchUploadTransport, createRef, createRemoteAttachmentService, createXhrUploadTransport, parseAttachmentDownloadTarget, parseAttachmentUploadTarget, parseRef };
+export {};
 //# sourceMappingURL=index.d.ts.map