# SQLI Wire Protocol Notes

> **Phase 0 spike artifact.** This is the byte-level reference document for the Informix SQLI wire protocol, derived from a combination of packet captures against the IBM Informix Developer Edition Docker image and clean-room study of the decompiled IBM JDBC driver (`com.ibm.informix:jdbc:4.50.4.1`). It is the canonical reference that all subsequent implementation phases depend on.
>
> **Current state**: scaffold only. Sections fill in as the spike proceeds.

---

## Source attribution conventions

Each documented byte sequence cites both sources of evidence:

- 🔵 **PCAP**: observed in `docs/CAPTURES/<file>.pcap` at offset `<n>`
- 🟡 **JDBC**: cross-referenced against `<class>.<method>()` in the decompiled tree (see `JDBC_NOTES.md`)

A finding is considered *confirmed* only when 🔵 and 🟡 corroborate. Single-source observations are flagged 🟠 *unverified*.

---

## 1. Connection establishment

### TCP setup
- Port: 9088 (SQLI native, default)
- Protocol: TCP, no TLS in plain mode
- Who speaks first: TBD

### Initial banner / capability exchange
TBD

---

## 2. Login sequence

### Message ordering
TBD

### Login packet structure
| Offset | Width | Field | Notes |
|--------|-------|-------|-------|
| TBD    | TBD   | TBD   | TBD   |

### Username encoding
TBD

### Password encoding (plain auth, no obfuscation)
TBD

### Database selection
TBD (during login, or separate USE-DATABASE message?)

### Server response on success
TBD

### Server response on auth failure
TBD

---

## 3. Message framing

### Header layout
TBD — fields: type tag, length, flags?

### Length field
- Width: TBD bytes
- Endianness: TBD
- Value semantics: payload-only or whole-message?

### Endianness (overall)
TBD

### Message type tags
| Tag (hex) | Direction | Name | Purpose |
|-----------|-----------|------|---------|
| TBD       | TBD       | TBD  | TBD     |

---

## 4. Statement execution: `SELECT 1`

### Request
TBD

### Response
TBD

### Type code observed for the literal `1`
TBD

---

## 5. Result-set framing

### Column descriptor block
TBD — fields per column: name, type code, precision/scale, nullability flag, …

### Row encoding
TBD — fixed-position fields? null bitmap? per-field length prefix?

### End-of-result marker
TBD

---

## 6. Error responses

### Error packet format
TBD — fields: SQLSTATE, native error code, message text

### Encoding
TBD

---

## 7. Disconnection

### Client→server logout message
TBD

### Server-side close behavior
TBD

---

## 8. Type codecs

### IDS type codes observed in column descriptors

| Code (decimal/hex) | IDS Type | Wire format | Notes |
|--------------------|----------|-------------|-------|
| TBD | SMALLINT  | TBD | |
| TBD | INTEGER   | TBD | |
| TBD | BIGINT    | TBD | |
| TBD | FLOAT     | TBD | |
| TBD | CHAR      | TBD | |
| TBD | VARCHAR   | TBD | |
| TBD | BOOLEAN   | TBD | |
| TBD | DATE      | TBD | 4-byte day count from 1899-12-31 (Informix epoch); confirm |

(DATETIME, INTERVAL, DECIMAL, BLOBs etc. are out of scope for Phase 0; see `DECISION_LOG.md`.)

---

## 9. Open questions

> List things observed in JDBC source or packet captures that we don't yet understand. Each entry is either resolved-and-removed or escalated to `DECISION_LOG.md` as a deferred item.

- _(none yet)_

---

## 10. Cross-checks

### JDBC ↔ PCAP corroboration matrix

| Phase 0 milestone | JDBC source confirms | PCAP confirms | Status |
|-------------------|----------------------|---------------|--------|
| Login byte layout | ⬜ | ⬜ | pending |
| `SELECT 1` round-trip | ⬜ | ⬜ | pending |
| Error response structure | ⬜ | ⬜ | pending |
| Disconnection | ⬜ | ⬜ | pending |

Phase 0 exit requires all four rows = ✅✅ confirmed.