# `Codex.Files.Registry`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.16.1/lib/codex/files/registry.ex#L1)

GenServer-backed manifest that tracks staged file attachments, deduplicates by checksum,
and prunes expired entries on a schedule. This powers the public `Codex.Files` helpers.

# `stage_opts`

```elixir
@type stage_opts() :: %{
  checksum: String.t(),
  name: String.t(),
  persist: boolean(),
  ttl_ms: :infinity | pos_integer(),
  size: non_neg_integer(),
  source_path: Path.t(),
  destination_path: Path.t()
}
```

# `stage_request`

```elixir
@type stage_request() :: {GenServer.from(), stage_opts(), DateTime.t()}
```

# `work_item`

```elixir
@type work_item() ::
  {:stage, String.t(), stage_opts()}
  | {:force_cleanup, GenServer.from(), DateTime.t()}
  | {:cleanup_tick, DateTime.t()}
  | {:reset, GenServer.from(), Path.t()}
  | :cleanup_orphaned_staging
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `ensure_started`

```elixir
@spec ensure_started() :: {:ok, pid()} | {:error, term()}
```

Ensures the registry is running under application supervision.

# `force_cleanup`

```elixir
@spec force_cleanup() :: :ok | {:error, term()}
```

Triggers an immediate cleanup pass to remove expired attachments.

# `list`

```elixir
@spec list() :: [Codex.Files.Attachment.t()]
```

Lists all staged attachments currently tracked in the manifest.

# `metrics`

```elixir
@spec metrics() :: map()
```

Aggregates counts, sizes, and TTL information for staged attachments.

# `reset`

```elixir
@spec reset(Path.t()) :: :ok | {:error, term()}
```

Clears the manifest and deletes staged files within the provided staging directory.

# `stage`

```elixir
@spec stage(stage_opts()) :: {:ok, Codex.Files.Attachment.t()} | {:error, term()}
```

Inserts or refreshes a staged attachment using the supplied options, returning the
canonical `Attachment` struct stored in ETS.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*