Skip to content

Commit 16f86a3

Browse files
VanderhellVanderhell
committed
docs: add iupd compatibility matrix
1 parent 04d6a82 commit 16f86a3

File tree

2 files changed

+292
-0
lines changed

2 files changed

+292
-0
lines changed

‎docs/IUPD_COMPATIBILITY.md‎

Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,291 @@
1+
# IUPD Compatibility and Surface Matrix
2+
3+
**Status**: Current repository implementation
4+
**Date**: 2026-04-06
5+
**Scope**: Compatibility rules across `.NET`, `native/ironfamily_c`, and `libs/ironcfg-c`
6+
7+
---
8+
9+
## 1. Scope
10+
11+
`IUPD` compatibility in this repository is not one flat rule set.
12+
13+
There are three materially different surfaces:
14+
15+
- `.NET` reader/writer in `libs/ironconfig-dotnet`
16+
- native strict verifier in `native/ironfamily_c`
17+
- legacy in-memory C API in `libs/ironcfg-c`
18+
19+
This document separates them explicitly.
20+
21+
---
22+
23+
## 2. Version Matrix
24+
25+
| Surface | Reads v1 | Reads v2 | Writes v1 | Writes v2 | Notes |
26+
|---|---|---|---|---|---|
27+
| `.NET` reader | yes | yes | n/a | n/a | current compatibility reader |
28+
| `.NET` writer | no | yes | no | yes | current emitted format is `v2` |
29+
| `native/ironfamily_c` strict verifier | no | yes | no | no | verification-only `v2` surface |
30+
| `libs/ironcfg-c` in-memory API | yes-style surface | not documented as full `v2` strict verifier | no | no | older compatibility surface |
31+
32+
### Practical truth
33+
34+
- if you need the active writer path, use `.NET v2`
35+
- if you need the active strict native verification path, use `native/ironfamily_c v2`
36+
- if you need the older in-memory C compatibility API, treat `libs/ironcfg-c` separately instead of assuming parity with the strict verifier
37+
38+
---
39+
40+
## 3. `.NET` Reader Compatibility
41+
42+
Current `.NET` reader accepts:
43+
44+
- `v1`
45+
- `v2`
46+
47+
### `v1`
48+
49+
Current compatibility behavior:
50+
51+
- accepted by header parser
52+
- mapped to profile `MINIMAL`
53+
- does not require `v2` profile byte
54+
- does not go through `v2`-only witness and profile-byte header rules
55+
56+
### `v2`
57+
58+
Current compatibility behavior:
59+
60+
- accepted by header parser
61+
- uses explicit profile byte
62+
- uses `37` byte header layout
63+
- enables witness, UpdateSequence, and incremental metadata logic according to profile
64+
65+
---
66+
67+
## 4. `.NET` Writer Compatibility
68+
69+
Current `.NET` writer behavior:
70+
71+
- emits `v2` only
72+
- does not emit `v1`
73+
- uses current `v2` header layout
74+
- writes profile byte
75+
- writes signature footer when profile requires strict signature semantics
76+
- writes `UpdateSequence` trailer when provided, and auto-injects `UpdateSequence(1)` for `SECURE` and `OPTIMIZED`
77+
- requires incremental metadata for `INCREMENTAL`
78+
79+
### Resulting compatibility rule
80+
81+
Current writer output should be described as:
82+
83+
- `v2-native` active repository output
84+
85+
It should not be described as a writer that targets both `v1` and `v2`.
86+
87+
---
88+
89+
## 5. Profile Acceptance Matrix
90+
91+
### Defined profiles in `.NET`
92+
93+
| Profile | Byte | Defined | Default writer support | Default reader acceptance |
94+
|---|---:|---|---|---|
95+
| `MINIMAL` | `0x00` | yes | yes | no for `v2` unless bench override |
96+
| `FAST` | `0x01` | yes | yes | no for `v2` unless bench override |
97+
| `SECURE` | `0x02` | yes | yes | yes |
98+
| `OPTIMIZED` | `0x03` | yes | yes | yes |
99+
| `INCREMENTAL` | `0x04` | yes | yes | yes |
100+
101+
### Current default `v2` acceptance in `.NET`
102+
103+
Accepted by default:
104+
105+
- `SECURE`
106+
- `OPTIMIZED`
107+
- `INCREMENTAL`
108+
109+
Rejected by default:
110+
111+
- `MINIMAL`
112+
- `FAST`
113+
114+
Override:
115+
116+
- `IRONFAMILY_BENCH_ALLOW_ALL_IUPD_PROFILES=1`
117+
118+
### Important consequence
119+
120+
There is a difference between:
121+
122+
- profile being defined in code
123+
- profile being writable
124+
- profile being accepted by default in strict repository validation
125+
126+
Those are not the same compatibility claim.
127+
128+
---
129+
130+
## 6. Integrity Compatibility
131+
132+
### CRC32
133+
134+
Current compatibility facts:
135+
136+
- all profiles carry per-chunk CRC32 in chunk entries
137+
- strict validation checks chunk CRC32
138+
- strict validation also checks manifest CRC32
139+
140+
### BLAKE3
141+
142+
Current compatibility facts:
143+
144+
- required for `SECURE`
145+
- required for `OPTIMIZED`
146+
- required for `INCREMENTAL`
147+
- not required for `MINIMAL`
148+
- not required for `FAST`
149+
150+
### Witness
151+
152+
Current compatibility facts:
153+
154+
- witness is a `v2` path
155+
- witness verification is skipped for `v1`
156+
- witness is enforced only for profiles that require witness strict semantics
157+
- current writer sets the witness-enabled flag for those profiles
158+
159+
---
160+
161+
## 7. Signature Compatibility
162+
163+
### `.NET`
164+
165+
Current `.NET` compatibility rules:
166+
167+
- signature footer is required for `SECURE`
168+
- signature footer is required for `OPTIMIZED`
169+
- signature footer is required for `INCREMENTAL`
170+
- signature length must be exactly `64`
171+
- verification key must be `32` bytes
172+
- signature algorithm path is Ed25519-based
173+
174+
### Native strict verifier
175+
176+
Current `native/ironfamily_c` docs state a narrower profile gate:
177+
178+
- profile must be `SECURE` or `OPTIMIZED`
179+
180+
That means the public native strict verifier documentation is currently narrower than the `.NET` reader’s accepted default `v2` profile set.
181+
182+
### Compatibility takeaway
183+
184+
Do not claim that every `.NET`-accepted strict profile is already identical to the documented native strict verifier contract.
185+
186+
---
187+
188+
## 8. UpdateSequence Compatibility
189+
190+
### `.NET`
191+
192+
Current `.NET` behavior:
193+
194+
- `UpdateSequence` trailer format is understood by the reader
195+
- for profiles requiring strict signature policy, missing `UpdateSequence` is a validation failure
196+
- optional replay guard can enforce monotonic progression
197+
198+
### Builder behavior
199+
200+
Current builder behavior:
201+
202+
- auto-injects `UpdateSequence(1)` for `SECURE`
203+
- auto-injects `UpdateSequence(1)` for `OPTIMIZED`
204+
- does not auto-inject it for every profile
205+
206+
### Native strict verifier
207+
208+
Current native strict verifier documents:
209+
210+
- `expected_min_update_sequence`
211+
- extracted `out_update_sequence`
212+
- anti-replay validation
213+
214+
So `UpdateSequence` is part of the active strict compatibility surface, not just an optional extension.
215+
216+
---
217+
218+
## 9. INCREMENTAL Compatibility
219+
220+
### `.NET`
221+
222+
Current `.NET` `INCREMENTAL` requirements:
223+
224+
- profile byte must be `INCREMENTAL`
225+
- signature strict path applies
226+
- witness strict path applies
227+
- metadata trailer must exist
228+
- metadata algorithm must be known
229+
- base hash must be present
230+
231+
Known metadata algorithms:
232+
233+
- `DELTA_V1` = legacy compatibility
234+
- `IRONDEL2` = active production path
235+
236+
### Native surfaces
237+
238+
Current repository native surfaces include:
239+
240+
- incremental metadata parser in `native/ironfamily_c`
241+
- delta2 apply path in `native/ironfamily_c`
242+
- diff apply path in `native/ironfamily_c`
243+
244+
But this still should not be described as one monolithic native `IUPD` API with full parity everywhere.
245+
246+
---
247+
248+
## 10. Native Surface Split
249+
250+
## 10.1 `native/ironfamily_c`
251+
252+
Current role:
253+
254+
- strict device-side `v2` verification
255+
- replay-aware verification
256+
- Ed25519 public-key verification
257+
- incremental metadata and delta support in adjacent headers
258+
259+
This is the active strict native path.
260+
261+
## 10.2 `libs/ironcfg-c`
262+
263+
Current role:
264+
265+
- older in-memory parse/validate/apply API
266+
- exposes `IUPD_VERSION 0x01`
267+
- not documented as the same thing as the strict `v2` verifier
268+
269+
This means compatibility statements must keep these two C surfaces distinct.
270+
271+
---
272+
273+
## 11. Safe Compatibility Claims
274+
275+
- `.NET` currently reads `v1` and `v2`
276+
- `.NET` currently writes `v2`
277+
- active strict native verification surface is `v2`
278+
- `libs/ironcfg-c` exposes a separate older `IUPD` C API surface
279+
- `SECURE`, `OPTIMIZED`, and `INCREMENTAL` are the default accepted strict `v2` profiles in `.NET`
280+
- `MINIMAL` and `FAST` are defined and writable in `.NET`, but not default-accepted for `v2` verification unless benchmark override is enabled
281+
- `INCREMENTAL` has additional compatibility requirements beyond base `v2` packaging
282+
283+
---
284+
285+
## 12. Claims To Avoid
286+
287+
- do not claim that all three surfaces share one identical `IUPD` compatibility contract
288+
- do not claim that the `.NET` writer emits both `v1` and `v2`
289+
- do not claim that `libs/ironcfg-c` is the same as the active strict native verifier
290+
- do not claim that `MINIMAL` and `FAST` are default-accepted `v2` strict profiles
291+
- do not claim full native parity for every `IUPD` path unless that specific path was verified separately

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Kept here:
1414
Primary engine docs:
1515

1616
- `IUPD_SPEC.md`
17+
- `IUPD_COMPATIBILITY.md`
1718
- `ILOG_SPEC.md`
1819
- `ILOG_SCHEMA_AND_TYPES.md`
1920
- `ICFG_SPEC.md`

0 commit comments

Comments
 (0)