docs/DEVELOPER.md

Sovereign Forge Developer Guide

Complete technical guide for Sovereign Forge contributors.

Architecture Deep Dive - Five Verification Layers

Layer 1: Verifier (src/verifier/sov_verifier.c)

• Performs exact int64_t arithmetic with overflow detection
• Executes matrix stack machine operations
• Validates memory safety via safe_alloc_matrix()
• No type checking, no obligation generation
• Return codes: VER_OK, VER_OVERFLOW, VER_UNDERFLOW, VER_BUFFER_OVERFLOW, VER_NULL_INPUT

Layer 2: Type System (src/typecheck/sov_types.c)

• Maintains type environment Gamma: variable names to (type, shape)
• Implements stack push/pop/peek with type tracking
• Infers types for matrix operations
• Tracks shape constraints: (rows, cols) pairs
• Detects type mismatches before execution

Layer 3: Obligation Generation (src/obligations/sov_obligations.c)

• Generates obligations from type inference failures
• Links each failed constraint to source location
• Creates obligation lists for external verification
• Obligation types: overflow_checks, underflow_checks, shape_matches, dimension_bounds

Layer 4: Certificate (src/certificate/sov_cert.c)

• Wraps execution history: initial stack, final stack, type environment
• Records program hash (SHA-256), instruction count, execution duration
• Encodes obligations in CBOR (RFC 8949) format
• Produces canonical JSON for round-trip verification
• Includes Blake3 + Ed25519 signatures for tamper detection

Layer 5: Receipt Chain (src/receipts/)

• Appends certificates to immutable WORM (write-once read-many) ledger
• Tracks certificate lineage: previous_hash to current_hash
• Stores on-chain metadata: timestamp, source authority, verification status
• Enables external verification without access to original program

Formal Semantics

Type judgments: Gamma |- i v tau, O, Gamma-prime

Where:

• Gamma = type environment (input)
• |- = yields or entails
• i = instruction code
• v = produces or executes to
• tau = type of result (MatrixI64, VectorI64, ScalarI64)
• O = obligations (constraints to verify)
• Gamma-prime = type environment (output)

Example 1: Gamma |- push(42) v ScalarI64, {}, Gamma Example 2: Gamma |- mul v MatrixI64, {shape_match(A.cols, B.rows)}, Gamma

How Obligations Are Generated

1. During type inference: sov_infer_instruction() checks compatibility
2. On mismatch: obligation record appended to obligation list
3. Obligation fields: type, pc, source_loc, constraint_text

Contributing to the Verifier Core

Exact Arithmetic Invariants

Critical invariants:

1. No silent overflow: check for int64_t overflow
2. Exact semantics: exact integer math only
3. Bounded dimensions: max 65536
4. Safe allocation: malloc() paired with overflow checks

Safe Arithmetic Functions

Use exclusively:

• __builtin_add_overflow(a, b, &result)
• __builtin_sub_overflow(a, b, &result)
• __builtin_mul_overflow(a, b, &result)

Testing: Write Conformance Test

1. Define test in tests/conformance/test_verifier.c
2. Register test in registry
3. Add adversarial case in tests/adversarial/
4. Run: make test-asan && make check-sanitizers

Sanitizer: Run before Submitting

• make test-asan (Address Sanitizer + UBSan)
• make run-fuzzer (libFuzzer, 10 seconds)
• make clean && make all && make run-tests

Address Sanitizer detects: overflows, use-after-free, double-free, leaks UBSan detects: integer overflow, division by zero, nullptr, out-of-bounds

Overflow: Use _builtin*_overflow

CORRECT: if (__builtin_add_overflow(a, b, &result)) return VER_OVERFLOW; WRONG: int64_t result = a + b;

Adding New Verification Operations

Step 1: spec/instruction-semantics.md

Add formal stack type transition.

Step 2: spec/type-rules.md

Document preconditions, postconditions, obligations.

Step 3: src/verifier/sov_verifier.c

1. Add operation code to .h
2. Implement verification function
3. Register in main dispatch

Step 4: Add Tests

Conformance and adversarial test cases.

Step 5: spec/verification-policy.md

Document obligation type and discharge.

Formal Verification Workflow

Step 1: Write Lean 4 Proof

Create theorem in proofs/lean4/.

Step 2: Extract to C

lean extract sov_custom_op.lean --output sov_custom_op_extracted.c

Step 3: Verify C Matches

Property tests in tests/property/.

Step 4: Publish Together

Link theorem to implementation.

Build System

Makefile.sov Overview

Main build: Makefile.sov (repo root) Variables: CC, CFLAGS, VERIFIER_SRCS, CERT_SRCS, OBL_SRCS, TYPE_SRCS Tests: CONFORMANCE_TESTS, ADVERSARIAL_TESTS

Available Targets

all - Build libsov_forge.a + tests libsov_forge.a - Static library test_verifier - Conformance (38 tests) test_infer - Type inference run-tests - Execute all test-asan - With ASan + UBSan check-sanitizers - Validate 46 tests run-fuzzer - libFuzzer (10s) clean - Remove artifacts

Adding New Test

1. Create tests/conformance/test_new_feature.c
2. Update Makefile.sov
3. Register in runner
4. Build: make clean && make test-asan

Code Style

C99, K&R Braces, 80-Column Comments

Function: VerifyResult sov_verify_operation(SafeMatrix *a, SafeMatrix *b) { if (!a || !b) { return VER_NULL_INPUT; } return VER_OK; }

K&R placement:

• Opening brace on same line as function/if/loop
• Closing brace on own line

No C++ Features

ALLOWED: stdlib.h, string.h, stdint.h, limits.h FORBIDDEN: vector, iostream, class

Explicit Error Returns

CORRECT: return VER_OVERFLOW WRONG: silent wrap or undefined behavior

Public Functions: extern in .h, definition in .c

Header: extern declaration Implementation: function body

Security Review Checklist

Before Code Review

• No unbounded loops: max 65536
• No string formatting: use memcpy
• No floats: int64_t only
• All mallocs: overflow check
• All buffer accesses: bounds check

Overflow Checking

Addition: __builtin_add_overflow(a, b, &res) Subtraction: __builtin_sub_overflow(a, b, &res) Multiplication: __builtin_mul_overflow(a, b, &res) Size: manual check before malloc

Memory Safety

make clean make CC=gcc CFLAGS="-fsanitize=address -g" test-asan valgrind --leak-check=full ./tests/conformance/test_verifier make CC=gcc CFLAGS="-fsanitize=undefined -g" test-asan

Release Process

Version Format

Development: vX.Y.Z-rcN Stable: vX.Y.Z

Signed Tags

git tag -s -m "Release v1.0.0" v1.0.0 git tag -v v1.0.0 git push origin v1.0.0

GitHub Releases

gh release create v1.0.0 --title "Sovereign Forge v1.0.0" make clean && make all gpg --armor --detach-sign libsov_forge.a sha256sum libsov_forge.a > libsov_forge.a.sha256 gh release upload v1.0.0 libsov_forge.a libsov_forge.a.asc libsov_forge.a.sha256

Announce Release

GitHub Discussions Academic mailing lists Security communities

Release Checklist

• Version bumped in src/verifier.h
• CHANGELOG.md updated
• All tests pass: make check-sanitizers
• Fuzzer runs 10s without crash: make run-fuzzer
• README.md current
• Signed tag created
• Artifacts built on clean checkout
• Reproducible build hash computed
• GitHub release created
• Announcement posted
• Tagged commit pushed

Questions & Support

1. Read spec: spec/instruction-semantics.md, spec/type-rules.md
2. Check tests: tests/conformance/, tests/adversarial/
3. File issue: Include reproduction steps, sanitizer output
4. Submit PR: Reference issue, include tests, pass all checks

---

Last updated: 2026-07-29 Maintainers: Sovereign Forge Team License: Apache 2.0 + AGPL 3.0

Detailed Implementation Guide

Safe Memory Management Deep Dive

Allocation with Overflow Prevention

Safe matrix allocation requires checking for multiplication overflow:

Step 1: Check rows * cols overflow size_t if (rows > 0 && cols > SIZE_MAX / rows) return NULL;

Step 2: Compute safe element count size_t nelems = rows * cols;

Step 3: Check nelems * sizeof(int64_t) overflow if (nelems > 0 && nelems > SIZE_MAX / sizeof(int64_t)) return NULL;

Step 4: Compute safe byte size size_t data_size = nelems * sizeof(int64_t);

Step 5: Allocate struct SafeMatrix *m = (SafeMatrix *)malloc(sizeof(SafeMatrix)); if (!m) return NULL;

Step 6: Allocate data buffer if (nelems > 0) { m->data = (int64_t *)malloc(data_size); if (!m->data) { free(m); return NULL; } }

Step 7: Initialize and return m->rows = rows; m->cols = cols; m->capacity = nelems; return m;

Buffer Validation

Every buffer access must be validated first:

VerifyResult validate_matrix_buffer( const int64_t *data, size_t rows, size_t cols, size_t capacity) { if (!data) return VER_NULL_INPUT; if (rows > 0 && cols > SIZE_MAX / rows) return VER_OVERFLOW; size_t required = rows * cols; if (required > capacity) return VER_BUFFER_OVERFLOW; return VER_OK; }

Type System Implementation

Type Environment Management

Type environment stores bindings from variable names to types:

typedef struct { char **var_names; ValType *var_types; Shape *var_shapes; uint32_t num_vars; } TypeEnv;

Operations:

• TypeEnv *sov_tyenv_new() creates new empty environment
• int sov_tyenv_add_var() adds binding (name, type, shape)
• int sov_tyenv_lookup_var() retrieves binding for name
• void sov_tyenv_free() deallocates environment

Capacity: 64 variables maximum to prevent unbounded allocation

Stack Operations with Type Tracking

Stack value structure includes ownership tracking:

typedef struct { ValType type; size_t rows; size_t cols; void *data; int is_owned; } StackValue;

Stack operations:

• Stack *sov_stack_new() creates stack
• int sov_stack_push() pushes value, check depth < 256
• int sov_stack_pop() pops value, check depth > 0
• StackValue *sov_stack_peek() access top without pop
• void sov_stack_free() deallocates stack

Type Inference Engine

Main inference function processes each instruction:

TypeCheckResult sov_infer_instruction( TypeEnv *env, Stack *stack, uint8_t opcode, uint8_t *operands)

For each instruction:

1. Check preconditions (stack depth, type constraints)
2. Pop input values from stack
3. Infer output type and shape
4. Generate obligations if constraints violated
5. Push result onto stack
6. Update type environment if necessary

Obligation Generation Details

Obligation Record Structure

typedef struct { uint8_t type; uint32_t pc; uint32_t source_line; char constraint_text[256]; uint8_t severity; } Obligation;

Types: OBLIG_STACK_UNDERFLOW, OBLIG_STACK_OVERFLOW, OBLIG_OVERFLOW, OBLIG_DIMENSION_BOUNDS, OBLIG_SHAPE_MISMATCH, OBLIG_TYPE_MISMATCH, OBLIG_NULL_POINTER, OBLIG_MEMORY_BOUNDS

Obligation List Management

typedef struct { Obligation *obligations; uint32_t count; uint32_t capacity; } ObligationList;

Operations:

• ObligationList *sov_obligations_new() creates empty
• int sov_obligations_add() appends and expands if needed
• void sov_obligations_free() deallocates all

Certificate Encoding

CBOR Serialization

Canonical CBOR encoding for portability:

Major types: 0=uint, 1=nint, 2=bstr, 3=tstr, 4=array, 5=map

Certificate structure (CBOR map): 0: program_hash (bytes, 32) 1: initial_stack (array of integers) 2: final_stack (array of integers) 3: obligations (array of maps) 4: timestamp (integer, UNIX seconds) 5: program_size (integer) 6: instruction_count (integer) 7: type_env_snapshot (map)

Canonical JSON Generation

JSON representation for human readability and verification:

• All object keys sorted alphabetically
• No whitespace (compact form)
• Numbers encoded as decimal strings for exact precision
• Hashes encoded as hex strings (lowercase)

Signature Generation

1. Compute Blake3 hash of canonical JSON
2. Sign Blake3 digest with Ed25519 private key
3. Include public key in certificate metadata
4. Signature = 64 bytes (Ed25519)
5. Public key = 32 bytes (Ed25519)

Receipt Chain Architecture

WORM Ledger Structure

Write-once read-many ledger stores immutable receipt history:

Receipt structure: index: receipt number (monotonically increasing) certificate_hash: SHA-256 of certificate previous_hash: SHA-256 of previous receipt timestamp: UNIX seconds when appended source_authority: identifier of appender verification_status: VERIFIED or UNVERIFIED

Ledger file format (JSONL):

• One receipt per line
• Each line is a complete JSON object
• Immutable: never modify or delete lines

Hash Chain Verification

To verify receipt N at index I:

1. Read receipt N: has certificate_hash and previous_hash
2. Read receipt N-1: has certificate_hash
3. Compute SHA-256 of receipt N-1 serialization
4. Verify computed hash = previous_hash of N
5. Continue to first receipt (previous_hash should be zero)

Test Structure

Conformance Test Framework

Conformance tests verify correct behavior with known inputs:

void test_operation_case(void) { SafeMatrix *input = safe_alloc_matrix(...); VerifyResult result = sov_verify_operation(...); ASSERT_EQ(result, VER_OK); ASSERT_EQ(output->data[i], EXPECTED_VALUE); safe_free_matrix(input); }

Test cases should cover:

• Boundary values (0, 1, MAX)
• Normal/typical inputs
• Edge cases (empty matrices, dimension 1)
• Full rows and columns

Adversarial Test Framework

Adversarial tests verify error handling:

void test_operation_failure(void) { SafeMatrix *a = safe_alloc_matrix(2, 3); SafeMatrix *b = safe_alloc_matrix(5, 4); VerifyResult result = sov_verify_operation(a, b, ...); ASSERT_EQ(result, VER_SHAPE_MISMATCH); safe_free_matrix(a); safe_free_matrix(b); }

Error cases should cover:

• Null pointers (NULL input)
• Shape mismatches (cols != rows)
• Overflow inputs (INT64_MAX)
• Underflow stack depth (empty stack)
• Dimension bounds (>65536)

Fuzzing with libFuzzer

libFuzzer generates random test inputs:

extern int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size);

Fuzz target:

1. Creates random matrices from fuzz input bytes
2. Calls verifier with random inputs
3. Checks for crashes, hangs, undefined behavior

Running: make run-fuzzer (runs for 10 seconds)

Performance Considerations

Complexity Analysis

Matrix multiplication: O(m * n * p) for m x n times n x p

For max dimensions (65536 x 65536 x 65536):

• Would require massive memory
• Not practical in real systems
• Bounded by memory allocation

Element-wise operations: O(m * n)

Benchmarking

Benchmark template:

1. Allocate input matrices
2. Record start time with clock_gettime()
3. Execute operation
4. Record end time
5. Compute elapsed time in nanoseconds
6. Report per-element processing rate

Integration Testing

Integration Test Scenarios

Scenario 1: Multi-operation sequence

• Load matrix A
• Load matrix B
• Multiply A*B = C
• Transpose C = D
• Verify final result

Scenario 2: Type inference with all operations

• Execute sequence of operations
• Verify type environment evolves correctly
• Check all shapes match expectations

Scenario 3: Full verification pipeline

• Execute program bytecode
• Generate type environment
• Generate obligations
• Create certificate
• Sign with Ed25519
• Append to WORM ledger
• Verify round-trip

Cross-layer Testing

Test Layer 1 (Verifier) alone: arithmetic, buffers Test Layer 1-2: type inference, shapes Test Layer 1-3: obligation generation Test Layer 1-4: certificate serialization, signatures Test Layer 1-5: full end-to-end with WORM ledger

Documentation Standards

Function Documentation

Every public function requires complete documentation:

/*

• sov_verify_matrix_multiply - Matrix multiplication with overflow.
• Description:
• Multiplies matrix A (m x n) by matrix B (n x p) to produce
• result (m x p). Performs exact arithmetic with int64_t
• overflow detection. Shape constraint: a->cols must equal
• b->rows.
• Arguments:
• a: Input matrix (m x n), must not be NULL, capacity >= m*n
• b: Input matrix (n x p), must not be NULL, capacity >= n*p
• result: Output (m x p), must not be NULL, capacity >= m*p
• Returns:
• VER_OK on success.
• VER_NULL_INPUT if argument is NULL.
• VER_SHAPE_MISMATCH if a->cols != b->rows.
• VER_OVERFLOW if multiply or add overflows.
• VER_BUFFER_OVERFLOW if result buffer too small.
• Side effects:
• Modifies result->data in place with product matrix.
• Thread safety:
• Not thread-safe. Caller must synchronize accesses. */

Test Documentation

Each test file documents its purpose:

/*

• test_verifier.c - Conformance tests for verifier layer.
• Tests the arithmetic correctness and safety properties of all
• verifier operations. Each test covers one operation with
• specific inputs designed to validate the operation's type
• signature and overflow behavior.
• Test coverage:
• • 38 conformance tests for all operations
• • Known inputs and expected outputs
• • Boundary values (0, 1, MAX, overflow) */

Code Review Checklist

When reviewing new operations:

1. Specification validation

   • Stack type judgment in spec/instruction-semantics.md
   • Type rule in spec/type-rules.md
   • Obligation types in spec/verification-policy.md

2. Implementation quality

   • All pointer arguments checked for NULL
   • All arithmetic uses _builtin*_overflow()
   • All buffer accesses validated with bounds check
   • No unbounded loops (max 65536)
   • Memory allocation checks for overflow

3. Test coverage

   • Conformance test with known values
   • Adversarial test with shape mismatch
   • Adversarial test with overflow
   • Adversarial test with null pointer
   • All tests pass with make test-asan

4. Documentation

   • Function header comment complete
   • Return codes documented
   • Side effects documented
   • Thread safety documented

5. Build system

   • Builds with make all without warnings
   • Tests registered in Makefile.sov
   • make clean removes all artifacts
   • make run-fuzzer completes without crash

6. Security

   • No format strings
   • No unbounded string operations
   • No floating-point arithmetic
   • No cryptographic shortcuts
   • All overflow cases handled

Continuous Integration

CI Pipeline Requirements

The CI system must verify:

1. Compilation stage

   • Compile with gcc -std=c99 -Wall -Wextra
   • Compile with clang for comparison
   • All warnings are errors

2. Testing stage

   • Run make test-asan (sanitizers)
   • Run make run-fuzzer (10 seconds)
   • Run make check-sanitizers (46 tests)

3. Coverage stage

   • Generate coverage report
   • Fail if coverage < 90%

4. Reproducibility stage

   • Clean checkout
   • Build with make all
   • Compute SHA-256 of all artifacts

5. Security stage

   • Run static analysis tools
   • Check for common vulnerabilities

Troubleshooting Common Issues

Build Failures

Issue: Undefined reference to function Solution: Ensure function is defined in .c file and declared in .h

Issue: Compilation warning about unused variable Solution: Remove unused variable or prefix with _ to suppress

Issue: Test fails but works locally Solution: Check for timezone/locale dependencies, use UTC

Sanitizer Reports

Issue: SEGV (segmentation fault) Solution: Null pointer dereference - add NULL check before use

Issue: Heap buffer overflow Solution: Validate buffer size before access - check bounds

Issue: Undefined Behavior Sanitizer integer overflow Solution: Use _builtin*_overflow instead of raw operators

Performance Optimization

Micro-optimizations

1. Inline simple functions to reduce call overhead

2. Avoid repeated bounds checks in tight loops Bad: for (i) { validate_access(data, i); data[i] = ... } Good: validate_once(); for (i) { data[i] = ... }

3. Use const pointers to enable compiler optimizations const int64_t *src = a->data;

4. Cache matrix dimensions in local variables size_t rows = m->rows; size_t cols = m->cols;

Profiling

Profile operations to identify bottlenecks:

perf record -g ./test_verifier perf report

This shows:

• Time spent in each function
• Cache misses and page faults
• Branch prediction failures

---

Document History:

• 2026-07-29: Complete version with 1200+ lines

Advanced Topics

Extending to Higher-Order Tensors

The current architecture supports 2D matrices. To extend:

1. Update Shape structure: typedef struct { uint8_t ndim; /* number of dimensions (2-4) / size_t dims[4]; / dimensions for each axis */ } Shape;

2. Update StackValue to use extended Shape

3. Implement tensor operations:

   • 3D tensor multiplication (batched matrix multiply)
   • Tensor transpose (arbitrary axis permutation)
   • Tensor reshape (change dimensions)
   • Tensor slice (extract subregion)

4. Add type rules for tensor operations

5. Implement conformance and adversarial tests

Parallelization Strategy

To parallelize matrix operations:

1. Partition matrix by rows (row-wise stripping)

   • Each thread computes subset of result rows
   • No false sharing if chunks large enough

2. Use OpenMP for thread pool: #pragma omp parallel for for (size_t i = 0; i < result_rows; i++) { for (size_t j = 0; j < result_cols; j++) { /* compute result[i][j] */ } }

3. Ensure atomicity of overflow checks

   • Overflow is local to each thread
   • Reduce error codes after computation

GPU Acceleration

To use GPU (CUDA/OpenCL):

1. Create GPU memory management layer

   • Copy SafeMatrix from host to device
   • Ensure device allocations check overflow
   • Copy results back to host

2. Implement GPU kernels for each operation

   • Matrix multiply (highly parallel)
   • Element-wise operations
   • Reductions (transpose, dot product)

3. Benchmark GPU vs CPU

   • GPU beneficial for large matrices (>1000x1000)
   • CPU better for small matrices (overhead)

Distributed Computing

To support distributed matrices:

1. Partitioning strategy:

   • 2D block partitioning across nodes
   • Each node stores block and computation logic

2. Communication protocol:

   • Send matrix blocks via MPI or gRPC
   • Ensure integrity of transmitted data

3. Consistency model:

   • Strong consistency: wait for all writes
   • Eventual consistency: read-repair

Persistence and Recovery

To support persistence:

1. Checkpointing strategy:

   • Periodic snapshots of all matrices
   • Save to disk with CRC checksums

2. Recovery on failure:

   • Load latest checkpoint
   • Verify checksum
   • Replay subsequent operations

3. Transaction log:

   • Write-ahead log (WAL) for durability
   • Each operation logged before execution
   • Replay log after crash

API Documentation

Public Headers

src/verifier/sov_verifier.h

Core verification functions:

SafeMatrix* safe_alloc_matrix(size_t rows, size_t cols)

• Allocate matrix with overflow checking
• Returns NULL on allocation failure
• Capacity automatically set

void safe_free_matrix(SafeMatrix *m)

• Deallocate matrix and its data
• Safe to call with NULL

VerifyResult validate_matrix_buffer( const int64_t *data, size_t rows, size_t cols, size_t capacity)

• Validate buffer size before access
• Returns VER_OK or specific error

VerifyResult sov_verify_push_constant(SafeMatrix *stack, int64_t value)

• Push constant value onto stack
• Stack must be allocated

VerifyResult sov_verify_pop(SafeMatrix *stack)

• Pop value from stack
• Check underflow before pop

src/typecheck/sov_types.h

Type inference functions:

TypeEnv *sov_tyenv_new(void)

• Create new type environment
• Empty environment with capacity 64

int sov_tyenv_add_var(TypeEnv *env, const char *name, ValType type, size_t rows, size_t cols)

• Add variable binding
• Check capacity not exceeded

src/obligations/sov_obligations.h

Obligation management:

ObligationList *sov_obligations_new(void)

• Create empty obligation list
• Initial capacity 32

int sov_obligations_add(ObligationList *list, uint8_t type, uint32_t pc, const char *text)

• Append obligation to list
• Auto-expand if capacity exceeded

src/certificate/sov_cert.h

Certificate functions:

ProofCertificate *sov_cert_new(void)

• Create new certificate
• Version 1, timestamp set

int sov_cert_set_stacks(ProofCertificate *cert, const int64_t *init, size_t init_len, const int64_t *final, size_t final_len)

• Set initial and final stacks
• Allocate and copy data

int sov_cert_to_cbor(ProofCertificate *cert, uint8_t *output, size_t output_size, size_t *written)

• Serialize certificate to CBOR
• Return number of bytes written

src/receipts/sov_receipts.h

Receipt ledger functions:

WormLedger *sov_ledger_open(const char *filepath)

• Open WORM ledger file
• Create if doesn't exist

int sov_ledger_append(WormLedger *ledger, const Receipt *receipt)

• Append receipt to ledger
• Assign index automatically
• Verify hash chain

Receipt *sov_ledger_read(WormLedger *ledger, uint64_t index)

• Read receipt at index
• Verify hash chain integrity

Version History

v1.0.0 (2026-07-29)

• Complete 5-layer architecture
• 46 conformance + adversarial tests
• ASan/UBSan sanitizer integration
• CBOR certificate encoding
• Ed25519 signature support
• WORM receipt ledger

Future v1.1.0

• 3D/4D tensor support
• OpenMP parallelization
• GPU acceleration
• Distributed matrix support

---

Complete Sovereign Forge Developer Guide Last updated: 2026-07-29 For questions: See Questions & Support section

Appendices

Appendix A: Common Error Codes

VER_OK = 0x00 Operation completed successfully.

VER_NULL_INPUT = 0x01 One or more required pointer arguments is NULL. Caller must provide valid non-NULL pointers.

VER_UNDERFLOW = 0x02 Stack depth less than required by operation. Operation needs N stack values but has M < N.

VER_OVERFLOW = 0x03 Integer arithmetic overflow detected in computation. Result exceeds int64_t range [INT64_MIN, INT64_MAX].

VER_BUFFER_OVERFLOW = 0x04 Buffer access exceeds allocated capacity. Attempt to access index >= capacity.

VER_SHAPE_MISMATCH = 0x05 Matrix dimensions incompatible for operation. Example: multiply requires cols[A] == rows[B].

VER_DIMENSION_OVERFLOW = 0x06 Result matrix dimensions exceed maximum (65536). Example: multiply 65536x65536 * 65536x65536.

VER_TYPE_MISMATCH = 0x07 Type system constraint violated. Stack value type does not match expected type.

VER_MEMORY_ERROR = 0x08 Memory allocation failed (malloc returned NULL). System out of memory or allocation too large.

Appendix B: Operation Reference

All operations with stack transitions:

PUSH Stack: [...] -> [..., ] Type: any scalar value

POP Stack: [..., X] -> [...] Type: X can be any type

ADD Stack: [..., A, B] -> [..., A+B] Type: scalar, scalar -> scalar

MUL (matrix multiply) Stack: [..., A, B] -> [..., AB] Type: matrix mn, matrix np -> matrix mp

TRANSPOSE Stack: [..., A] -> [..., A^T] Type: matrix mn -> matrix nm

SCALE Stack: [..., A, s] -> [..., s*A] Type: matrix, scalar -> matrix

DOT Stack: [..., A, B] -> [..., sum(A*B)] Type: vector, vector -> scalar

Appendix C: Build Commands Reference

make all Build library and all tests. Default target.

make libsov_forge.a Build static library only (no tests).

make test_verifier Build and link verifier conformance tests.

make run-tests Compile and run all tests with output.

make test-asan Build with ASan/UBSan and run conformance+adversarial.

make check-sanitizers Alias for test-asan (same functionality).

make run-fuzzer Build libFuzzer and run for 10 seconds.

make clean Remove all compiled objects, binaries, archives.

Appendix D: Environment Setup

On Linux (Ubuntu/Debian):

sudo apt update sudo apt install build-essential gcc clang valgrind

On macOS (Homebrew):

brew install gcc clang valgrind

On Windows (MSYS2):

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-toolchain

Appendix E: Git Workflow

1. Clone repository: git clone https://github.com/USER/sovereign-forge.git cd sovereign-forge

2. Create feature branch: git checkout -b feature/new-operation

3. Make changes: vim src/verifier/sov_verifier.c vim tests/conformance/test_verifier.c

4. Build and test: make clean && make test-asan

5. Commit changes: git add src/verifier/sov_verifier.c tests/conformance/test_verifier.c git commit -m "feat: add new operation"

6. Push to GitHub: git push origin feature/new-operation

7. Create pull request on GitHub

8. After review, merge to main: git checkout main git pull origin main git merge --no-ff feature/new-operation git push origin main

Appendix F: Debugging Tips

Using GDB

gdb ./tests/conformance/test_verifier (gdb) break sov_verify_multiply (gdb) run (gdb) print result->data[0] (gdb) continue

Using Valgrind

valgrind --leak-check=full ./tests/conformance/test_verifier

Sanitizer Output Interpretation

SUMMARY: AddressSanitizer: 0 errors Indicates no memory errors detected.

SUMMARY: UndefinedBehaviorSanitizer: integer-overflow Indicates integer overflow without the builtin check. Fix by wrapping with _builtin*_overflow().

---

End of Sovereign Forge Developer Guide Complete technical reference for all contributors