# FIFO–01: one task, one contract

Version: fifo-v1. Canonical prompt language: English. Freeze this file and the
acceptance testbench before running any provider. This is a proposed comparison
protocol, not a published benchmark result.

## Assignment

Implement a synthesizable single-clock synchronous FIFO in SystemVerilog.

File: rtl/fifo.sv. Module name: fifo. Parameters WIDTH=8 and DEPTH=16.
DEPTH is a power of two and at least 2. Also support WIDTH=16, DEPTH=4.

Ports:

```systemverilog
input  logic             clk,
input  logic             rst,
input  logic             in_valid,
output logic             in_ready,
input  logic [WIDTH-1:0] in_data,
output logic             out_valid,
input  logic             out_ready,
output logic [WIDTH-1:0] out_data
```

The interface declarations above illustrate widths; the final module must use
valid complete parameterized SystemVerilog syntax.

- rst is active-high and synchronous. It clears occupancy and pointers.
- A push occurs on a rising edge when in_valid && in_ready and !rst.
- A pop occurs on a rising edge when out_valid && out_ready and !rst.
- in_ready is true exactly when occupancy < DEPTH. It is false when full,
  even if out_ready is true in that cycle.
- out_valid is true exactly when occupancy > 0.
- out_data exposes the oldest stored word when out_valid is true; it may be
  unspecified when empty. There is no empty-FIFO fall-through.
- Simultaneous push/pop preserves occupancy and FIFO order.
- Reset has priority over push/pop. Do not require clearing the memory array.

Provide RTL, a cocotb test suite, a minimal reproducible simulation command,
and a short explanation. Do not modify the acceptance testbench. Do not add
network dependencies, generated IP, or proprietary simulator requirements.

## Common acceptance gates

The experiment owner must prepare one independent read-only testbench, pin its
revision/hash, and use it unchanged for all runs. Agent-authored tests are useful
artifacts but are not an independent acceptance oracle.

1. Compile and lint with the same pinned tool versions.
2. Reset while idle and while data is queued.
3. Check empty/full boundaries, rejected pushes/pops and stable ordering.
4. Check simultaneous push/pop, wraparound and output backpressure.
5. Run a seeded random scoreboard test (seed 42, at least 1000 cycles).
6. Repeat for WIDTH=16, DEPTH=4.

Do not call a run successful until every fixed acceptance gate passes.

## Fair comparison

- Same task and repository revision, same read-only testbench.
- Record agent version, exact model ID, region and API/subscription storefront.
- Same time/tool/retry budgets and model settings where comparable.
- Start clean. Save every prompt, response, tool invocation and repair loop.
- Use billed provider usage. Do not estimate tokens from visible answer length.
- Record input (including cache reads), cached reads, output/reasoning, cache
  writes, largest single prompt, retries, elapsed time and test outcome.
- Keep subscription quota/credits separate from API token billing.

## CSV import

Required columns (UTF-8, comma-separated):

task_id,provider,model,input_tokens,cached_input_tokens,output_tokens,max_prompt_tokens,passed

task_id must be fifo-v1. Provider IDs: claude, openai, kimi, zai, qwen, minimax, mimo.
The calculator only uses a model rate when the exact imported model matches its
verified model example and the encoded context tier is applicable. It excludes
cache writes, tool fees and other charges. Retain those separately in the trace;
this estimate is not an invoice or measured subscription capacity.

Blank counts mean not measured. A zero count is a measured numerical value,
not a substitute for missing data. No provider measurements ship with the site.