Guid

Designed, not built. Nothing on this page compiles today; every sample carries // no-run for that reason. What runs is the type reference, and this page is kept apart from it on purpose (the specs index).

Guid is C#'s System.Guid: a 128-bit identifier, written as f81d4fae-7dec-11d0-a765-00a0c91e6bf6, compared and ordered by value, with an all-zero Guid.Empty and a random Guid.NewGuid().

It is the smallest page in this plan because it invents nothing: the sixteen-byte value, the machine module that moves it and the member-lowering table are all built by docs/specs/decimal.md and docs/specs/datetime.md, and this page spends them. What it adds is 16 bytes of layout, a hex parser, a hex formatter and a byte comparison — and one blocked function.

1. Representation #

type_new("Guid", 16, 16, TK_WIDE)

Sixteen bytes, sixteen-byte aligned, TK_WIDE — docs/specs/decimal.md § 1's registration exactly, moved by teko_wide.tk's three derived machine tables, by address and never in a register pair. Everything in that page's "How sixteen bytes travel" applies here word for word and is not repeated.

The sixteen bytes are in text order, big-endian, byte 0 first:

That is RFC 4122's own order and the order the "D" format prints, which makes ToString a straight walk from byte 0 to byte 15 and Parse its inverse. It is not C#'s in-memory order: System.Guid stores _a as an int and _b/_c as shorts, so on a little-endian host its first eight bytes are byte-swapped relative to the text. The difference is invisible everywhere the surface can see it — ToString, Parse, == and != give identical answers either way — and it is visible in exactly two places C# users know are traps:

• CompareTo and the ordering operators. C# compares _a as a signed int, then _b, then _c as signed shorts, then the remaining bytes — an order almost nobody intends and SQL Server famously disagrees with. teko compares the sixteen bytes unsigned, left to right, which is the order the text sorts in. Recorded as a divergence, § 6.
• ToByteArray() and new Guid(byte[]), which are not in this design at all.

2. The surface #

Legal.

// no-run
#include "guid.tk"

i64 main() {
    Guid a = Guid.Parse("f81d4fae-7dec-11d0-a765-00a0c91e6bf6");
    Guid b = Guid.Parse("F81D4FAE-7DEC-11D0-A765-00A0C91E6BF6");   // case-insensitive
    if (a != b) return 1;
    if (a == Guid.Empty) return 2;

    str s = a.ToString();                        // the "D" form, lowercase
    if (Guid.Parse(s) != a) return 3;
    if (a.ToString("N") != "f81d4fae7dec11d0a76500a0c91e6bf6") return 4;

    Guid z = Guid.Empty;
    if (z.ToString() != "00000000-0000-0000-0000-000000000000") return 5;
    if (z >= a) return 6;                        // ordered by the bytes, left to right

    Guid out_v = Guid.Empty;
    if (Guid.TryParse("nope", out out_v) != 0) return 7;
    return 42;
}

Illegal, and what each one earns.

// no-run
#include "guid.tk"

i64 main() {
    Guid a = Guid.Empty;
    i64 n = a;                    // teko: a value of type Guid does not convert to i64
    Guid b = 0;                   // teko: a value of type i64 does not convert to Guid
    Guid c = a + a;               // teko: no operator `+` takes these operands
    i64 d = (i64) a;              // teko: a Guid does not cast; `.ToString()` writes it
    Guid e = Guid.NewGuid();      // teko: Guid.NewGuid is not taught yet
    return 0;
}

3. Operators #

Every one is a call, because a sixteen-byte value has no cmp — the same rule docs/specs/decimal.md § 5 states. The comparison walks the bytes from +0, unsigned, and stops at the first difference.

4. The API #

Text. ToString() writes 36 characters, lowercase, 8-4-4-4-12, which is C#'s "D" and C#'s own casing. ToString("N") writes the same 32 hex digits with no dashes. "B" (braces), "P" (parentheses) and "X" (the C struct form) are not taught: they are three more formats for the same sixteen bytes and nothing asks for them.

Parse accepts "D" and "N", either case, and panics on anything else (teko: the string is not a Guid). TryParse(s, out g) answers 0/1 and writes Guid.Empty on failure — the C# pair, and the reason out is worth having. tk_guid_fmt(ptr buf, Guid g, i64 fmt) is the allocation-free half, the split <float_rt> makes between putf64 and fmt_f64.

.IsEmpty is not a C# member — C# writes g == Guid.Empty — and it is here because it is one comparison the caller would otherwise write against a static that costs a load. It is the one addition on this page, and it is additive: g == Guid.Empty works too.

5. Guid.NewGuid is blocked on mc #

A version-4 Guid is sixteen bytes of cryptographically random data with the version nibble set to 4 and the variant bits to 10. The nibbles are arithmetic; the randomness is not, and teko cannot get it:

mc has no conditional compilation, the five legs compile one source, and the Windows leg resolves <sys>'s libc-shaped names through mc's own runtime object, which is mc's file and not this repository's. Writing a second include per host, or a [libs]/[externs] mapping in the leg config, would push an operating-system choice into every consumer's teko.toml for one function — which is exactly the workaround docs/specs/datetime.md § 8 refuses for the wall clock, for the same reasons.

The ask is one function, and it goes to mc's notices file beside the wall clock:

i64 sys_random(uptr buf, i64 n);      // n bytes of entropy; 0 on success

one name across the three hosts, getrandom/getentropy under it on the two POSIX legs and BCryptGenRandom on Windows. It unblocks on whichever mc release carries it. Until then Guid.NewGuid is refused by name, and every other member of this page lands without it.

A Guid built from a counter, a clock or an address would compile and would be a wrong answer — two processes would collide — so it is not the fallback. There is no fallback; there is a refusal and a filed ask.

6. What stays out #

7. The hooks, by module #

8. What it costs in mc limits #

The machine module adds no row: teko_wide.tk is already derived, and a derived table shadows the name it registers rather than consuming a machines slot.

9. Fixtures #

Every one is a whole program with #include "../lib/guid.tk", returning 42 on success and a small distinct number per failed assertion.

10. The crumb #

N3 — Guid (M) #

The registration, the tables, lib/guid.tk, and the NewGuid refusal. Depends on docs/specs/decimal.md's C3 for teko_wide.tk and the sixteen-byte value, and on docs/specs/datetime.md's C1 for the primitive-member and primitive-operator tables. It depends on nothing else — in particular not on decimal's arithmetic, so it can land between C3 and C4.

Gate: the four fixtures at their exit codes on all five legs — a sixteen-byte value in a parameter and a return is what a single leg cannot prove — every other fixture unchanged with --dump-ast byte-identical, FIXPOINT OK, mc limits verdict ok with passes and intrin not moved, sh scripts/check-docs.sh green. Owes: a Guid section in types.md, the refusals in diagnostics.md, lib/guid.tk in runtime.md, the NewGuid row in not-yet.md, and the new module in modules.md.

N9 — Guid.NewGuid (S, blocked) #

One static row, one call into lib/guid.tk, one fixture asserting that two consecutive NewGuid() values differ, that the version nibble is 4 and that the variant bits are 10. Blocked until mc's <sys> carries § 5's entropy function on the three hosts.

11. Risks and law tensions #

Edit this page