oxedyne/fe2o3 — fe2o3_sbj/fixtures/README.md

oxedyne/fe2o3/fe2o3_sbj/fixtures/README.md

3.7 KiB, 10 runs

created by r1870400018:21946, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1	# SBJ conformance fixtures
2
3	The teeth of `SPEC.md` §7. Written by `examples/gen_fixtures.rs`, run by `tests/conformance.rs`, and
4	regenerated rather than patched:
5
6	cargo run -p oxedyne_fe2o3_sbj --example gen_fixtures
7	cargo test -p oxedyne_fe2o3_sbj
8
9	Each fixture is a directory.
10
11	Acceptance fixtures carry `doc.jdat`, the payload in JDAT text form and the source of truth;
12	`doc.sbj`, the canonical signed artefact; and `meta.jdat`, what the artefact must turn out to be:
13	its address, the length of its payload region, and -- where the payload is a node tree -- its node
14	count and its depth. The suite reads `doc.jdat`, signs it with the committed key, and requires the
15	bytes it gets back to be `doc.sbj`, byte for byte.
16
17	Not every payload is a node tree. The container carries any schema (§1.2), and the fixtures
18	named `post_`, `card_` and `share_*` carry `daimond/post/0`, `daimond/card/0` and
19	`daimond/share/0`, which are flat canonical maps rather than trees. Those declare no node count and
20	no depth, because they have neither, and their `doc.jdat` is written in plain JDAT with none of the
21	`sbj_` node labels below. Everything else about them is identical: the same header, the same
22	envelope, the same address, the same signature, and every rule of §3.
23
24	The `share_*` fixtures carry one rule the others do not, and it is the reason that schema exists:
25	`code` is the sender's SIGNED statement about whether the share carries a program, and it is
26	checked against the files both ways. `share_code_hidden` is a page under a claim of no code, and
27	`share_code_claimed_without_code` is the opposite. A share is a COPY the receiver comes to own, so
28	there is no live view, nothing to revoke, and no third party in the middle of it.
29
30	Rejection fixtures carry `doc.sbj`, the bad artefact, and `reject.jdat`, which declares the rule
31	broken, the step of §2 that must catch it, what the error must say, and the node or the byte it must
32	name. "It was rejected" is not the claim: the claim is that it was rejected for the right reason.
33	A rejection fixture also carries `doc.jdat` where the tree region is the encoding of a tree that can
34	be written down; where the fault is in the bytes themselves, there is no tree to write.
35
36	Every rejection fixture past the header is correctly hashed and correctly signed, so that the
37	rejection can only have come from the rule the fixture breaks, and never from a signature that
38	happened not to check out.
39
40	`key.jdat` holds the fixed key every fixture is signed with, and a second key that signs nothing but the
41	fixture of a signature by the wrong hand. It is committed on purpose: a fixture signed by a fresh
42	key would be a different file on every run, and a suite that has to be regenerated to pass tests
43	nothing. It is a test key, published here, and signs nothing else.
44
45	Node labels in `doc.jdat` carry an `sbj_` prefix, because two of the v0 kind labels, `box` and
46	`list`, are JDAT's own kind labels as well: `(box\|{..})` would read back as a `Dat::Box`. None of
47	this reaches the wire, where BDAT carries the `u16` kind code and no label at all.
48
49	The kind code 99 appears in the `unknown_kind` and `unknown_kind_fallback` fixtures. It names no v0
50	node kind, which is the point of it: the first carries no fallback and is refused, and the second
51	carries a fallback of known nodes and is accepted (§4.5).
52
53	The kind codes 14 (`edit`) and 15 (`surface`) appear in the three `reserved_*` fixtures. They are
54	not unknown: §4.2 reserves them to the chrome and to applications, and `oxeweb/doc/0` admits the
55	kinds 1 to 13 and no others. All three are refused, and the third carries a valid fallback and is
56	refused anyway, which is the point of it: a fallback admits a code the reader has never heard of,
57	and never one the reader knows a document may not carry.