# AudioIngress
`kcode-audio-ingress` is a standalone Rust library for durable, automatic
audio transcription. It accepts a complete owned audio buffer, persists the
original before returning, delegates transcription to
`kcode-audio-transcribe`, and persists the canonical transcript.
It is not an HTTP service. Multipart parsing, upload-size policy, browser
responses, transcript splitting, and delivery into Kennedy memory belong to
the embedding application.
## Public API
The intentionally small surface is:
```rust
let ingress = AudioIngress::open(persistence_root, transcriber).await?;
let submitted = ingress.submit(AudioInput {
bytes,
recorded_at,
original_filename,
}).await?;
let status = ingress.status()?;
ingress.retry(recording_id)?;
```
- `open` accepts one persistence-root path and an `AudioTranscriber`.
- `submit` accepts one `Vec<u8>` plus the recording time and optional original
filename. It returns only after the original and job record are durable.
- `status` returns all recording identities, metadata, processing progress,
completed transcripts, and failures.
- `retry` requeues one failed recording after a caller has decided that the
external problem was corrected.
Callers do not drive individual processing stages. Opening and submitting wake
the library's background worker automatically.
## Persistence and identity
AudioIngress owns everything below its configured root:
```text
<root>/
state.sqlite3
originals/
```
Originals are content-addressed by SHA-256. Submitting identical bytes is
idempotent even when the filename changes. The library has no storage quota and
does not remove originals; an embedding application may reject an input before
submission or manage deployment-level capacity outside the library.
There is no streaming submission API. `kcode-audio-transcribe` requires the
complete audio in memory, so retaining a second streaming abstraction would
only complicate the boundary without reducing the peak memory requirement.
## Processing and retries
The durable public states are queued, processing, complete, and failed.
Processing progress is the typed `kcode-audio-transcribe` status with any
transcript body removed; the canonical transcript appears only in the complete
state.
AudioIngress automatically retries a retryable full-job failure up to five
times, with a short fixed delay between attempts. A structurally invalid input
or another non-retryable dependency failure stops immediately. Once automatic
attempts are exhausted, no further work occurs until `retry` resets the
five-attempt budget. Retry policy is deliberately not configurable.
An active external transcription job exists only in memory. If the process
stops, the accepted original and latest durable progress remain, and opening
the library starts a fresh attempt from the original bytes.
## Boundary with `kcode-audio-transcribe`
`kcode-audio-transcribe` owns audio validation, working-audio preparation,
chunk planning, provider calls, per-step progress, and transcript
reconciliation. AudioIngress adds durable input ownership, content identity,
whole-job recovery, the standard five-attempt lifecycle, and a minimal status
API. It does not reimplement transcription or transcript reconciliation.
## Boundary with KennedyServer
KennedyServer owns:
- Axum routes and multipart parsing;
- upload-size limits and other deployment policy;
- conversion of library status into browser-facing JSON;
- splitting completed transcripts for Kennedy memory ingress;
- downstream claims, checkpoints, retries, failures, and completion;
- the global Kweb writer lane.
Consequently no Axum, HTTP, `OpaquePiece`, delivery-failure, streaming, or
Kennedy/Kweb type appears in the standalone library API.
## Managed-library packaging
The crate is conforming source for `kcode-rust-libs-v2`. Its root manifest has
literal standalone package metadata and explicit dependency requirements.
`Documentation.md` is the complete agent-facing API reference. Generated
`Cargo.lock` and build artifacts are not managed package source.