[feat] Enforce semantics for write once memory (wom)

memory design space.md

@@ -0,0 +1,73 @@
+# Memory design space
+
+Designing a memory module `m` requires at a minimum categorizing it along the following dimensions:
+
+- **ACCESS**: how do other modules communicate with it ?
+- **COHERENCE**: is a coherence argument (i.e. memory consistency argument) required ?
+- **MUTABILITY**: is that memory mutable or immutable ?
+- **ADDRESS SPACE**: is data stored in a contiguous fashion or can it be sparse ?
+- **SEGMENTATION**: is the memory accessible across several trace segments or not ?
+
+We provide constraints for memories below:
+
+## RAM: Random Access Memory
+
+- **ACCESS**: logUpBus based
+- **COHERENCE**: logUpBus-based `Σ ≡ 0` coherence argument involving timestamps
+- **MUTABILITY**: unrestricted reads and writes
+- **ADDRESS SPACE**: sparse
+- **SEGMENTATION**: multi-segment
+
+Use case: standard computer memory
+
+## AOM: Access Once Memory
+
+**AOM**'s provide an immutable memory that gets read start to finish in a single segment.
+
+**Note.** I suggest using **AOM** as a replacement for **ROM** / **WOM**: these two notions are functionally identical and differ, AFAICT, only in their intended use cases. Both are meant to hold immutable data that's avaiable from the start of tracing, and either seen as _providing_ inputs or _receiving_ output. In any case, they are functionally identical.
+
+- **ACCESS**: lookup based
+- **COHERENCE**: none required
+- **MUTABILITY**: immutable
+- **ADDRESS SPACE**: contiguous
+- **SEGMENTATION**: all accesses concentrated in one segment
+
+Use case: provide inputs or extract outputs in one go,
+e.g. read `m` start to finish in one trace segment.
+
+## WOM: Write Once Memory
+
+**WOM**'s provide an initially empty memory where every cell may be read from and written to, but the initial write is definitive.
+
+- **ACCESS**: logUpBus based
+- **COHERENCE**: logUpBus-based `Σ ≡ 0` coherence argument involving timestamps
+- **MUTABILITY**:
+  - arbitrary reads
+  - first write sets value in stone (subsequent writes mustn't modify the current value)
+  - first write marks an address as `WAS_ALREADY_WRITTEN_TO`
+- **ADDRESS SPACE**: contiguous
+- **SEGMENTATION**: multi-segment
+
+Use case: extract definitive outputs that may be read by other processes
+
+- is `m` single access ?
+  - there are concrete cases (e.g. guest program ELF sections, guest program input)
+  - can it be assumed that the accesses land in a single trace segment ? if so one doesn't have to care about inter segment coherence
+- is `m`
+  - immutable ?
+  - set once ?
+  - arbitrarily modifiable ?
+  - the answer to that question dictates whether one requires whether access must be tracked or not
+  - e.g. for WRITE ONCE MEMORY one should track
+- is memory access confined to a single segment ?
+  - the answer to that question dictates whether
+    - memory consistency can be handled in module (and without permutation) or should be handled using a bus argument
+    - whether timestamps are required to order accesses or not
+- does the memory permit writes ?
+  - if so, does it permit more than one write per address ?
+- does the memory permit reads ?
+- are accesses sequential and confined to a single segment or can they occur at any point in the execution ?
+  - one can talk of the ONE TIME ACCESS property
+- are accesses sequential and confined to a single segment or can they occur at any point in the execution ?
+- does the touched address space have gaps ?
+  - CONTIGUOUS memory allows potential initialization / finalization phases to increment addresses via `addr.next() = addr + 1`

pkg/ir/hir/constraint.go

@@ -84,7 +84,7 @@ func NewPermutationConstraint(handle string, context schema.ModuleId, targets []
 	return Constraint{permutation.NewConstraint[word.BigEndian](handle, context, targets, sources)}
 }
 
-// NewRangeConstraint constructs a new Range constraint!
+// NewRangeConstraint constructs a new Range constraint
 func NewRangeConstraint(handle string, ctx schema.ModuleId, expr Term,
 	bitwidth uint) Constraint {
 	//

pkg/ir/mir/constraint.go

@@ -64,13 +64,27 @@ func NewLookupConstraint[F field.Element[F]](handle string, targets []LookupVect
 	return Constraint[F]{lookup.NewConstraint(handle, targets, sources)}
 }
 
+// NewSendConstraint creates a new "send to logUpBus" constraint; it doesn't take into account
+// the potential Id of the logup bus, which would for instance determine what shared randomness to use.
+func NewSendConstraint[F field.Element[F]](handle string, sources []register.Id) Constraint[F] {
+	// TODO
+	return Constraint[F]{}
+}
+
+// NewReceiveConstraint creates a new "receive from logUpBus" constraint; it doesn't take into account
+// the potential Id of the logup bus, which would for instance determine what shared randomness to use.
+func NewReceiveConstraint[F field.Element[F]](handle string, sources []register.Id) Constraint[F] {
+	// TODO
+	return Constraint[F]{}
+}
+
 // NewPermutationConstraint creates a new permutation
 func NewPermutationConstraint[F field.Element[F]](handle string, context schema.ModuleId, targets []register.Id,
 	sources []register.Id) Constraint[F] {
 	return Constraint[F]{permutation.NewConstraint[F](handle, context, targets, sources)}
 }
 
-// NewRangeConstraint constructs a new Range constraint!
+// NewRangeConstraint constructs a new Range constraint
 func NewRangeConstraint[F field.Element[F]](handle string, ctx schema.ModuleId, registers []*RegisterAccess[F],
 	bitwidths []uint) Constraint[F] {
 	//

pkg/schema/constraint/ranged/constraint.go

@@ -43,7 +43,7 @@ type Constraint[F field.Element[F], E term.Evaluable[F]] struct {
 	Bitwidths []uint
 }
 
-// NewConstraint constructs a new Range constraint!
+// NewConstraint constructs a new Range constraint
 func NewConstraint[F field.Element[F], E term.Evaluable[F]](handle string, context schema.ModuleId,
 	exprs []E, bitwidths []uint) Constraint[F, E] {
 	return Constraint[F, E]{handle, context, exprs, bitwidths}

pkg/schema/constraint/vanishing/constraint.go

@@ -47,7 +47,7 @@ type Constraint[F field.Element[F], T term.Testable[F]] struct {
 	Constraint T
 }
 
-// NewConstraint constructs a new vanishing constraint!
+// NewConstraint constructs a new vanishing constraint
 func NewConstraint[F field.Element[F], T term.Testable[F]](handle string, context schema.ModuleId,
 	domain util.Option[int], constraint T) Constraint[F, T] {
 	return Constraint[F, T]{handle, context, domain, constraint}

pkg/test/zkc_unit_test.go

@@ -32,6 +32,14 @@ var DEFAULT_UNIT_CONFIG = util.DEFAULT_CONFIG.
 var DEFAULT_UNITBIG_CONFIG = DEFAULT_UNIT_CONFIG.
 	Words(vm.WORD_UINT128)
 
+// ===================================================================
+// example test
+// ===================================================================
+
+func Test_ZkcUnit_Example(t *testing.T) {
+	checkZkcUnit(t, "zkc/unit/_example", DEFAULT_UNIT_CONFIG.Constraints(true).GoGen(false))
+}
+
 // ===================================================================
 // Basic Tests
 // ===================================================================

pkg/zkc/compiler/ast/decl/decl.go

@@ -25,8 +25,12 @@ type Resolved = Declaration[symbol.Resolved]
 // reference to an external component (e.g. function, RAM, ROM, etc).
 type Unresolved = Declaration[symbol.Unresolved]
 
-// Declaration represents something declared within a source file, such as a
-// function or constant, etc.
+// Declaration represents something declared within a source file, in particular
+// - includes
+// - constants
+// - input / output / memory / static "memories"
+// - functions
+// - type aliases
 type Declaration[S any] interface {
 	// Arity returns the number of inputs/outputs for this declaration.
 	Arity() (inputs uint, outputs uint)

pkg/zkc/compiler/codegen/statement.go

@@ -88,7 +88,8 @@ func (p *StmtCompiler) compileStatement(pc uint, mapping []uint, s Stmt) VectorI
 //
 // > struct tmp { x u32, y u32 }
 // > ...
-// > var t tmp > tmp = f(...)
+// > var t tmp
+// > tmp = f(...)
 //
 // In this case, we want to "compile out" the struct, so we end up with this:
 //