/* SPDX-License-Identifier: LicenseRef-Starship-1.0 * Copyright (c) 2023-2026 Robert A. James */ /* test_mkf18a.c -- the host tool's artifact, read back unit by unit (ARTIFACT.md). * * docs/v4.0.0/plans/2026-11-19-f18-artifact-build.md section 4, test 3. Two small trains are written to * a scratch directory: LIB, one word, and TRAIN, which imports it. Each is built by f18a_build, as mkf18a * builds it, and its artifact is read back against the layout: the header, the provenance, every export, * import and relocation, the verification record and the code. The code and the addresses are checked * against text.c assembling the same text on a node of its own, the oracle. Then what the tool must * refuse, and what the checker must refuse. */ #define _POSIX_C_SOURCE 200809L #include "v4/artifact.h" #include "v4/text.h" #include "../tools/f18a.h" #include "starkernel/sha512.h" #include "starkernel/xxhash64.h" #include #include #include #include static int failures = 0, checks = 0; #define CHECK(c,...) do{checks++; if(!(c)){failures++; printf("FAIL %s:%d: ",__FILE__,__LINE__); printf(__VA_ARGS__); printf("\n");}}while(0) #ifndef SCRATCH #error "SCRATCH must name a directory the test may write in" #endif #ifndef V4_ROOT #error "V4_ROOT must name the v4 directory, for the tool's hash" #endif #define PORT 900 static char err[256]; static v4_node n; static v4_text tx; static v4_text_addr rec[256]; static void put(const char *dir, const char *name, const char *text) { char path[512]; FILE *f; mkdir(SCRATCH, 0777); mkdir(dir, 0777); snprintf(path, sizeof path, "%s/%s", dir, name); f = fopen(path, "wb"); if (!f) { printf("cannot write %s\n", path); exit(1); } fputs(text, f); fclose(f); } static int save(const char *path, const unsigned char *a, size_t len) { FILE *f = fopen(path, "wb"); if (!f) return 0; fwrite(a, 1, len, f); fclose(f); return 1; } /* the build of `dir`, with MAP, ROM and the trains given; NULL, err set, if it is refused */ static const char *nucleus; /* `import nucleus` builds against it when set */ static unsigned char *build(const char *dir, const f18a_train *trains, unsigned ntrains, size_t *len) { f18a_args a; unsigned char *out = NULL; a.map = SCRATCH "/map.f18"; a.dir = dir; a.rom = SCRATCH "/rom.c"; a.trains = trains; a.ntrains = ntrains; a.tool_root = V4_ROOT; a.nucleus = nucleus; err[0] = 0; if (!f18a_build(&a, &out, len, err, sizeof err)) return NULL; return out; } static int refused(const char *dir, const f18a_train *trains, unsigned ntrains, const char *what) { size_t len; unsigned char *a = build(dir, trains, ntrains, &len); if (a) { free(a); printf(" built, not refused\n"); return 0; } if (!strstr(err, what)) { printf(" refused: %s\n", err); return 0; } return 1; } static uint32_t U(const unsigned char *a, size_t u) { return v4_f18a_unit(a, u); } /* the counted string at pool offset `off` equals `s` */ static int pool_is(const unsigned char *a, const v4_f18a_layout *l, uint32_t off, const char *s) { size_t i, len = strlen(s); const unsigned char *p = a + (l->pool + off) * 4u; if (off == 0 || off >= l->s) return 0; if (p[0] != len) return 0; for (i = 0; i < len; i++) if (p[1 + i] != (unsigned char)s[i]) return 0; return 1; } /* the export named `s`: its first unit, or 0 */ static size_t export_of(const unsigned char *a, const v4_f18a_layout *l, const char *s) { uint32_t i; for (i = 0; i < l->e; i++) if (pool_is(a, l, U(a, l->exports + 8u * i), s)) return l->exports + 8u * i; return 0; } /* SHA-512 over files as the provenance frames them: each its name, a NUL, its length in 8 bytes low * first, its bytes */ static void frame(sha512_ctx_t *c, const char *name, const char *text) { unsigned char len[8]; size_t n_ = strlen(text); unsigned i; for (i = 0; i < 8; i++) len[i] = (unsigned char)((unsigned long long)n_ >> (8 * i)); sha512_update(c, (const uint8_t *)name, strlen(name) + 1u); sha512_update(c, len, 8); sha512_update(c, (const uint8_t *)text, n_); } static int hash_is(const unsigned char *a, size_t u, const unsigned char h[64]) { return memcmp(a + u * 4u, h, 64) == 0; } static int all_zero(const unsigned char *a, size_t u, size_t count) { size_t i; for (i = 0; i < count; i++) if (U(a, u + i) != 0) return 0; return 1; } static const char MAP[] = "constant (PORT) 900\n"; static const char LIB_SQ[] = ": SQ dup + ;\n"; static const char BASE[] = ": DUP2 over over ;\n: ADD3 + + ;\n"; static const char USE[] = "import LIB SQ\n" ": USE DUP2 ADD3 SQ ;\n" ": LOOP FOR dup NEXT ;\n" ": PUT ports (PORT) b! !b ;\n" ": REQ request 7 7 (PORT) b! !b ;\n" ": FL inline pinned mode 2 push ;\n" ": PTR &DUP2 ;\n"; int main(void) { unsigned char *lib, *a, *b; size_t lib_len, len, len2; v4_f18a_layout l, ll; const char *why = NULL; f18a_train trains[1]; size_t x; unsigned i; printf("v4 mkf18a: V4_CELL_BITS=%d\n", V4_CELL_BITS); /* the scratch directory holds only the files written here, each written afresh on every run */ put(SCRATCH, "map.f18", MAP); put(SCRATCH, "rom.c", "/* a ROM */\n"); put(SCRATCH "/lib", "00-sq.f18", LIB_SQ); put(SCRATCH "/train", "00-base.f18", BASE); put(SCRATCH "/train", "10-use.f18", USE); /* LIB: one word, no imports */ lib = build(SCRATCH "/lib", NULL, 0, &lib_len); CHECK(lib != NULL, "LIB builds: %s", err); if (!lib) goto done; CHECK(v4_f18a_check(lib, lib_len, V4_CELL_BITS, &ll, &why), "LIB's artifact is valid: %s", why ? why : ""); CHECK(ll.e == 1 && ll.i == 0 && ll.r == 0 && export_of(lib, &ll, "SQ"), "LIB exports SQ and nothing else"); CHECK(save(SCRATCH "/lib.f18a", lib, lib_len), "LIB saved"); /* TRAIN, importing LIB's SQ */ trains[0].name = "LIB"; trains[0].path = SCRATCH "/lib.f18a"; a = build(SCRATCH "/train", trains, 1, &len); CHECK(a != NULL, "TRAIN builds: %s", err); if (!a) goto done; CHECK(v4_f18a_check(a, len, V4_CELL_BITS, &l, &why), "TRAIN's artifact is valid: %s", why ? why : ""); /* the oracle: the same text, assembled by text.c at 0 on a node of its own */ v4_node_reset(&n); v4_text_begin(&tx, &n, 0); v4_text_record(&tx, rec, 256); CHECK(v4_text_assemble(&tx, MAP) && v4_text_assemble(&tx, BASE) && v4_text_assemble(&tx, USE) && v4_text_finish(&tx), "the oracle assembles: %s", v4_text_error(&tx)); /* the header (ARTIFACT.md section 3) */ CHECK(U(a, 0) == V4_F18A_MAGIC && U(a, 1) == 0 && U(a, 2) == V4_CELL_BITS && U(a, 3) == V4_NODE_WORDS, "magic F18A, ABI 0, the cell width, the node words"); CHECK(l.e == 7, "seven exports: DUP2 ADD3 USE PUT REQ FL PTR, and not LOOP, which has no fixed effect -- %u", l.e); CHECK(l.i == 1 && l.r == v4_text_addresses(&tx), "one import; a relocation for each address the oracle records (%u, %u)", l.r, v4_text_addresses(&tx)); CHECK(l.c == (uint32_t)v4_text_here(&tx), "the code: the oracle's cells (%u, %ld)", l.c, (long)v4_text_here(&tx)); CHECK(U(a, 9) == 16u + 64u, "the exports after the header and the provenance"); CHECK(all_zero(a, 10, 6), "the header's reserved units 0"); CHECK(len == (l.code + 0u) * 4u + (size_t)l.c * (V4_CELL_BITS / 8u), "the length: the records, then the code"); /* the provenance (section 4) */ { sha512_ctx_t c; unsigned char h[64]; sha512_init(&c); frame(&c, "00-base.f18", BASE); frame(&c, "10-use.f18", USE); sha512_final(&c, h); CHECK(hash_is(a, 16, h), "the source hash: the train's .f18, in name order"); sha512_init(&c); frame(&c, "rom.c", "/* a ROM */\n"); sha512_final(&c, h); CHECK(hash_is(a, 16 + 48, h), "the ROM's hash"); CHECK(!all_zero(a, 16 + 16, 16) && !all_zero(a, 16 + 32, 16), "the tool's hash and the configuration's"); CHECK(memcmp(a + 16 * 4 + 16 * 4, lib + 16 * 4 + 16 * 4, 64) == 0, "the same tool for both trains"); CHECK(memcmp(a + 16 * 4, lib + 16 * 4, 64) != 0, "different sources, different hashes"); } /* the exports (section 5) */ { static const struct { const char *name; unsigned dt, dl, rt, rl; uint32_t flags; } want[] = { { "DUP2", 2, 4, 0, 0, 0 }, { "ADD3", 3, 1, 0, 0, 0 }, { "USE", 2, 2, 0, 0, 0 }, { "PUT", 1, 0, 0, 0, 0 }, { "REQ", 0, 0, 0, 0, 0 }, { "FL", 1, 0, 0, 1, 8 | 64 | (2 << 8) }, }; for (i = 0; i < sizeof want / sizeof want[0]; i++) { x = export_of(a, &l, want[i].name); CHECK(x != 0, "%s is exported", want[i].name); if (!x) continue; CHECK(U(a, x + 1) == (uint32_t)v4_text_word(&tx, want[i].name), "%s's entry: the oracle's", want[i].name); CHECK(U(a, x + 2) == want[i].flags, "%s's flags: %x", want[i].name, U(a, x + 2)); CHECK(U(a, x + 3) == (want[i].dt | (want[i].dl << 16)) && U(a, x + 4) == (want[i].rt | (want[i].rl << 16)), "%s's effects: %x %x", want[i].name, U(a, x + 3), U(a, x + 4)); CHECK(U(a, x + 6) == 0 && U(a, x + 7) == 0, "%s's reserved units 0", want[i].name); } CHECK(export_of(a, &l, "PTR") && U(a, export_of(a, &l, "PTR") + 3) == (0u | (1u << 16)), "PTR: 0 -> 1"); CHECK(export_of(a, &l, "LOOP") == 0, "LOOP, a loop that leaves a count, is not exported"); x = export_of(a, &l, "PUT"); CHECK(x && U(a, x + 5) == 0x80000000u, "PUT's capabilities: ports, no requests"); x = export_of(a, &l, "REQ"); CHECK(x && (U(a, x + 5) & 0x80000000u) == 0 && (U(a, x + 5) & 0x7FFFFFFFu) != 0 && U(a, l.pool + (U(a, x + 5) & 0x7FFFFFFFu)) == 1 && U(a, l.pool + (U(a, x + 5) & 0x7FFFFFFFu) + 1) == 7, "REQ's capabilities: the list 1, 7"); x = export_of(a, &l, "DUP2"); CHECK(x && U(a, x + 5) == 0, "DUP2's capabilities: none"); } /* the import */ { uint64_t id = xxhash64(lib, lib_len, 0); CHECK(U(a, l.imports) == (uint32_t)id && U(a, l.imports + 1) == (uint32_t)(id >> 32), "the import names LIB's capsule ID"); CHECK(pool_is(a, &l, U(a, l.imports + 2), "SQ"), "the import's name, SQ"); CHECK(U(a, l.imports + 3) == (1u | (1u << 16)) && U(a, l.imports + 4) == 0, "the effects expected: LIB's, 1 -> 1"); CHECK(U(a, l.imports + 5) == 0, "the import's reserved unit 0"); } /* the relocations: the oracle's record, in order */ for (i = 0; i < l.r && i < v4_text_addresses(&tx); i++) { uint32_t u0 = U(a, l.relocs + 2u * i), u1 = U(a, l.relocs + 2u * i + 1u); CHECK((u0 & 0x1FFFFFFFu) == (uint32_t)rec[i].cell && (u0 >> 29) == rec[i].slot && u1 == (rec[i].import < 0 ? V4_F18A_INTERNAL : (uint32_t)rec[i].import), "relocation %u: cell %u slot %u -> %x", i, u0 & 0x1FFFFFFFu, u0 >> 29, u1); } /* the verification record, empty, and the code, low byte first */ CHECK(all_zero(a, l.verify, 18), "no proof: the verification record is 0"); { int same = 1; for (i = 0; i < l.c; i++) { v4_ucell v = 0; unsigned k; for (k = 0; k < V4_CELL_BITS / 8u; k++) v |= (v4_ucell)a[l.code * 4u + (size_t)i * (V4_CELL_BITS / 8u) + k] << (8u * k); if ((v4_cell)v != n.mem[i]) same = 0; } CHECK(same, "the code: the oracle's cells, each low byte first"); } /* reproducible */ b = build(SCRATCH "/train", trains, 1, &len2); CHECK(b && len2 == len && memcmp(a, b, len) == 0, "built again: the same bytes"); free(b); /* what the checker refuses */ { unsigned char *c = malloc(len); memcpy(c, a, len); c[0] ^= 1; CHECK(!v4_f18a_check(c, len, V4_CELL_BITS, &ll, &why), "a wrong magic"); memcpy(c, a, len); c[10 * 4] = 1; CHECK(!v4_f18a_check(c, len, V4_CELL_BITS, &ll, &why), "a reserved unit not 0"); memcpy(c, a, len); CHECK(!v4_f18a_check(c, len - 1, V4_CELL_BITS, &ll, &why), "a short artifact"); CHECK(!v4_f18a_check(c, len, V4_CELL_BITS == 64 ? 32 : 64, &ll, &why), "the other cell width"); memcpy(c, a, len); c[(l.relocs) * 4] = 0xFF; c[(l.relocs) * 4 + 1] = 0xFF; CHECK(!v4_f18a_check(c, len, V4_CELL_BITS, &ll, &why), "a relocation outside the code"); memcpy(c, a, len); c[(l.exports + 1) * 4 + 2] = 0x7F; CHECK(!v4_f18a_check(c, len, V4_CELL_BITS, &ll, &why), "an export's entry outside the code"); memcpy(c, a, len); c[(l.relocs + 1) * 4] = 5; c[(l.relocs + 1) * 4 + 1] = 0; c[(l.relocs + 1) * 4 + 2] = 0; c[(l.relocs + 1) * 4 + 3] = 0; CHECK(!v4_f18a_check(c, len, V4_CELL_BITS, &ll, &why), "an import index beyond the imports"); free(c); } /* what the tool refuses */ put(SCRATCH "/r1", "00.f18", "header H : H ;\n"); CHECK(refused(SCRATCH "/r1", NULL, 0, "header"), "a header in a train's source"); put(SCRATCH "/r2", "00.f18", ": W ; store 100 5\n"); CHECK(refused(SCRATCH "/r2", NULL, 0, "store"), "a store"); put(SCRATCH "/r3", "00.f18", ": W ; start W\n"); CHECK(refused(SCRATCH "/r3", NULL, 0, "start"), "a start"); put(SCRATCH "/r4", "00.f18", ": P (PORT) b! !b ;\n"); CHECK(refused(SCRATCH "/r4", NULL, 0, "ports"), "a port it can see, not declared"); put(SCRATCH "/r5", "00.f18", ": R 7 (PORT) b! !b ;\n"); CHECK(refused(SCRATCH "/r5", NULL, 0, "request"), "a request it can see, not declared"); put(SCRATCH "/r6", "00.f18", ": P ports (PORT) b! !b ;\n: Q P ;\n"); CHECK(refused(SCRATCH "/r6", NULL, 0, "ports"), "a call to a word that touches ports, not declared"); put(SCRATCH "/r7", "00.f18", "import NONE X\n: W X ;\n"); CHECK(refused(SCRATCH "/r7", NULL, 0, "NONE"), "an import from a train not given"); put(SCRATCH "/r8", "00.f18", "import LIB NOPE\n: W NOPE ;\n"); CHECK(refused(SCRATCH "/r8", trains, 1, "NOPE"), "an import the train does not export"); put(SCRATCH "/r9", "00.f18", ": A-NAME-OF-THIRTY-TWO-CHARACTERS2 ;\n"); CHECK(refused(SCRATCH "/r9", NULL, 0, "31"), "an export's name longer than the dictionary's 31"); put(SCRATCH "/r10", "00.f18", ": P ports request 3 3 (PORT) b! !b (PORT) 1 + b! !b ;\n: Q ports request 3 P ;\n"); { size_t l10; unsigned char *c = build(SCRATCH "/r10", NULL, 0, &l10); CHECK(c != NULL, "declared, it builds: %s", err); free(c); } /* imports from the nucleus (section 12, rulings 3 and 4): hash 0, the effect derived from the nucleus * as the tool assembles it, by its dictionary name */ put(SCRATCH "/n1", "00.f18", "import nucleus ABS\n: DIST inv 1 + + ABS ;\n"); CHECK(refused(SCRATCH "/n1", NULL, 0, "nucleus"), "an import from the nucleus, with no nucleus given"); nucleus = V4_SYS_DIR; { size_t ln; unsigned char *c = build(SCRATCH "/n1", NULL, 0, &ln); v4_f18a_layout lc; CHECK(c != NULL, "an import from the nucleus builds: %s", err); if (c) { CHECK(v4_f18a_check(c, ln, V4_CELL_BITS, &lc, &why) && lc.i == 1, "valid, with one import"); CHECK(U(c, lc.imports) == 0 && U(c, lc.imports + 1) == 0, "the nucleus's hash: 0"); CHECK(pool_is(c, &lc, U(c, lc.imports + 2), "ABS"), "the import's name, ABS"); CHECK(U(c, lc.imports + 3) == (1u | (1u << 16)) && U(c, lc.imports + 4) == 0, "ABS's effect from the nucleus: 1 -> 1"); x = export_of(c, &lc, "DIST"); CHECK(x && U(c, x + 3) == (2u | (1u << 16)), "DIST, calling it, 2 -> 1"); free(c); } } put(SCRATCH "/n2", "00.f18", "import nucleus NOPE\n: W NOPE ;\n"); CHECK(refused(SCRATCH "/n2", NULL, 0, "NOPE"), "a name the nucleus does not have"); put(SCRATCH "/n3", "00.f18", "import nucleus SCR\n: W SCR ;\n"); CHECK(refused(SCRATCH "/n3", NULL, 0, "in line"), "a word in line in the nucleus, which cannot be called"); put(SCRATCH "/n4", "00.f18", "import nucleus UM*\n: W UM* ;\n"); CHECK(refused(SCRATCH "/n4", NULL, 0, "no fixed effect"), "a nucleus word with no fixed effect"); nucleus = NULL; free(a); done: free(lib); printf(" %d checks, %d failures\n", checks, failures); return failures ? 1 : 0; }