///|
/// Opaque, single-owner streaming multipart/form-data writer.
declare pub type MultipartWriter

///|
/// Create a writer using an explicit validated boundary and hard limits.
declare pub fn MultipartWriter::new(
  boundary : String,
  limits : @model.Limits,
) -> MultipartWriter raise @model.MultipartError

///|
/// Return the HTTP Content-Type value for this writer.
declare pub fn MultipartWriter::content_type(self : MultipartWriter) -> String

///|
/// Begin one part and return its delimiter plus canonical headers.
declare pub fn MultipartWriter::begin_part(
  self : MultipartWriter,
  meta : @model.PartMeta,
) -> Bytes raise @model.MultipartError

///|
/// Forward one raw body chunk after enforcing total and per-part limits.
declare pub fn MultipartWriter::write(
  self : MultipartWriter,
  chunk : Bytes,
) -> Bytes raise @model.MultipartError

///|
/// End the current part. This is a lifecycle transition and does not imply
/// that another part will follow.
declare pub fn MultipartWriter::end_part(
  self : MultipartWriter,
) -> Bytes raise @model.MultipartError

///|
/// Close the message and emit the final delimiter.
declare pub fn MultipartWriter::finish(
  self : MultipartWriter,
) -> Bytes raise @model.MultipartError

///|
/// Number of bytes returned by writer operations.
declare pub fn MultipartWriter::bytes_emitted(self : MultipartWriter) -> Int64

///|
/// One body whose byte length is known before a request is sent.
declare pub type PlannedPart

///|
/// Exact wire-size plan for a sequence of multipart parts.
declare pub type MultipartPlan

///|
/// Build a limit-checked wire-size plan without retaining any body bytes.
declare pub fn plan(
  boundary : String,
  parts : Array[PlannedPart],
  limits : @model.Limits,
) -> MultipartPlan raise @model.MultipartError

///|
/// Construct one plan input from metadata and a known non-negative body size.
declare pub fn PlannedPart::new(
  meta : @model.PartMeta,
  body_length : Int64,
) -> PlannedPart raise @model.MultipartError

///|
/// Return the exact Content-Length in bytes for this plan.
declare pub fn MultipartPlan::content_length(self : MultipartPlan) -> Int64

///|
/// Return a copy of plan inputs in emission order.
declare pub fn MultipartPlan::parts(self : MultipartPlan) -> Array[PlannedPart]

///|
/// Stateful emitter that verifies actual chunks match a prior `MultipartPlan`.
declare pub type PlannedEmitter

///|
/// Create an emitter from a plan, reusing its validated boundary and limits.
declare pub fn PlannedEmitter::new(
  plan : MultipartPlan,
) -> PlannedEmitter raise @model.MultipartError

///|
/// Begin the next declared part and return its multipart framing.
declare pub fn PlannedEmitter::begin_next(
  self : PlannedEmitter,
) -> Bytes raise @model.MultipartError

///|
/// Emit one body chunk while ensuring it cannot exceed the planned length.
declare pub fn PlannedEmitter::write_chunk(
  self : PlannedEmitter,
  chunk : Bytes,
) -> Bytes raise @model.MultipartError

///|
/// End the active part after checking its exact planned body length.
declare pub fn PlannedEmitter::end_next(
  self : PlannedEmitter,
) -> Bytes raise @model.MultipartError

///|
/// Finish an emitter only after every planned part has been completed.
declare pub fn PlannedEmitter::finish(
  self : PlannedEmitter,
) -> Bytes raise @model.MultipartError