Phase 0: stable ID types, deterministic RNG, and common utilities #42

Manually merged

erikinkinen merged 4 commits from 0-stable-id-types-and-utilities into main

2026-02-04 10:10:23 +01:00

erikinkinen commented

2026-02-04 09:59:48 +01:00

Owner

Task

Closes #2

Summary

This PR introduces stable, deterministic foundational utilities required by all later AES phases:

strong, domain-separated ID types (SubjectId, ObjectId, EdgeId, EventId),
centralized and disciplined ID generation,
a deterministic RNG wrapper with explicit seed and stream splitting,
common assertion and error-handling helpers.

These changes establish reproducibility, type safety, and invariant enforcement without introducing any authority semantics or simulation behavior.

Scope

Included

Strongly typed ID wrappers with explicit invalid state
Centralized, monotonic ID generation discipline
Deterministic PRNG with explicit seed + stream splitting
Lightweight assertion (AES_ASSERT, AES_CHECK) and error utilities
Minimal documentation of ID and RNG discipline

Explicitly excluded

Authority semantics or graph logic
Revocation or provenance modeling
Persistence, replay, or logging formats
Experimental workloads or metrics

Design rationale

IDs are plain, monotonic integers wrapped in strong types to prevent accidental mixing across domains while remaining cheap to store, log, and replay.
ID allocation is centralized to a single choke point, ensuring determinism and preventing accidental reuse or drift.
RNG usage is explicit and structured: a root RNG is seeded once, and all subsystems receive deterministic substreams via splitting. This prevents unrelated code changes from perturbing existing randomness.
Assertions vs. errors are separated deliberately:
- assertions protect internal invariants,
- errors report recoverable failures (e.g. invalid input, IO).

This provides a stable substrate on which later semantic phases can build safely.

Invariants checked

IDs are deterministic, monotonic, and never reused within a run
ID domains are type-separated and cannot be mixed accidentally
RNG output is deterministic across runs given identical seed/streams
Randomness can be partitioned without cross-subsystem interference
Invariant violations fail fast and diagnostically

Verification

Builds locally
CI smoke build passes
Basic ID and RNG tests pass
No semantic behavior introduced

### Task Closes #2 --- ### Summary This PR introduces **stable, deterministic foundational utilities** required by all later AES phases: * strong, domain-separated ID types (`SubjectId`, `ObjectId`, `EdgeId`, `EventId`), * centralized and disciplined ID generation, * a deterministic RNG wrapper with explicit seed and stream splitting, * common assertion and error-handling helpers. These changes establish reproducibility, type safety, and invariant enforcement without introducing any authority semantics or simulation behavior. --- ### Scope **Included** * Strongly typed ID wrappers with explicit invalid state * Centralized, monotonic ID generation discipline * Deterministic PRNG with explicit seed + stream splitting * Lightweight assertion (`AES_ASSERT`, `AES_CHECK`) and error utilities * Minimal documentation of ID and RNG discipline **Explicitly excluded** * Authority semantics or graph logic * Revocation or provenance modeling * Persistence, replay, or logging formats * Experimental workloads or metrics --- ### Design rationale * **IDs** are plain, monotonic integers wrapped in strong types to prevent accidental mixing across domains while remaining cheap to store, log, and replay. * **ID allocation** is centralized to a single choke point, ensuring determinism and preventing accidental reuse or drift. * **RNG usage** is explicit and structured: a root RNG is seeded once, and all subsystems receive deterministic substreams via splitting. This prevents unrelated code changes from perturbing existing randomness. * **Assertions vs. errors** are separated deliberately: * assertions protect internal invariants, * errors report recoverable failures (e.g. invalid input, IO). This provides a stable substrate on which later semantic phases can build safely. --- ### Invariants checked * [x] IDs are deterministic, monotonic, and never reused within a run * [x] ID domains are type-separated and cannot be mixed accidentally * [x] RNG output is deterministic across runs given identical seed/streams * [x] Randomness can be partitioned without cross-subsystem interference * [x] Invariant violations fail fast and diagnostically --- ### Verification * [x] Builds locally * [x] CI smoke build passes * [x] Basic ID and RNG tests pass * [x] No semantic behavior introduced