File size: 6,880 Bytes
fadf040 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | # Foundry F1 — Pure-J Core API Surface
Mapping of the C++ mathematical surface to J Core verbs/nouns.
**No implementation.** Names, ranks, and domains only.
Preferred license for derivative pure-J work: **AGPL-3.0**.
Convention: J ranks — `0` atom, `1` list/vector, `2` table/matrix, `3` rank-3. Domains name the mathematical carrier.
---
## Nouns (data carriers)
| Noun | Rank | Domain | Maps from |
|------|------|--------|-----------|
| `Fp` | 0 | atom `u64` with \(0 \le v < p\) | `Goldilocks::Elem` |
| `FpVec` | 1 | list of `Fp` | batch Elem arrays |
| `Signature` | 1 | length-2 integer list `(delta_source; delta_target)` | `pmc::Signature` |
| `PMatEntry` | 1 | boxed/record: `sign (±1)`, `Signature`, `row`, `col` | `pmc::PMatEntry` |
| `PMat` | 1–2 | sparse list of `PMatEntry` plus shape `(rows; cols)` | `pmc::PMat` |
| `Jacobian` | 2 | real matrix \( n\times n \) | `vector<vector<double>>` spectral input |
| `State` | 1 | real vector \( x_t \) | recurrence state |
| `Weights` | 1 | length-2 (or dim) real list for Ξ / Λ schedule row | `xi_schedule_[t]`, `lambda_schedule_[t]` |
| `StepInfo` | 0–1 | record: `step`, `q`, `epsilon`, `n_xi`, `n_lam`, `projected`, `residual` | `pmc::StepInfo` |
| `SpectralResult` | 0–1 | record: `spectral_radius`, `contractive`, `gershgorin_bound`, `power_iter_bound`, `used_power_iteration` | `SpectralGovernor::Result` |
| `AceCert` | 0–1 | record: `lipschitz_upper`, `safety_margin`, `tail_bound`, `certified` | `pmc::AceCertificate` |
| `Tier` | 0 | enum atom T1..T4 | `pmc::Tier` |
| `GatePolicy` | 0 | enum: PassThrough / Suppress / Hold / Attenuate | `pmc::GatePolicy` |
| `P64` | 1 | length-64 list of first primes | `pmc::P_64` |
| `PrimeMask` | 0 | `u64` bitmask over `P64` indices | `pmc::PrimeMask` |
| `ResonanceWord` | 0 | `u64` packed class∥payload | `pmc::ResonanceWord` |
### Named constant nouns (must match PROPERTIES.md)
| Noun | Rank | Value source |
|------|------|--------------|
| `GOLDILOCKS_PRIME` / `p` | 0 | `0xFFFFFFFF00000001` = 18446744069414584321 |
| `EPSILON_FOLD` | 0 | `0xFFFFFFFF` = \(2^{32}-1\) (fold; README name `EPSILON`) |
| `K_MAX` | 0 | 133144 |
| `MAX_DRIFT` | 0 | 300000000000000000 |
| `PIRTM_MAGIC` | 0 | `0x7F504952` |
| `PHI` | 0 | 1.618033988749895 |
| `tier_epsilon` | 0←0 | T1:0.10 T2:0.05 T3:0.02 T4:0.01 |
---
## Verbs — Goldilocks field
| Verb | Rank | Domain → range | Meaning |
|------|------|----------------|---------|
| `fp_reduce` | 0→0 | `u64` → `Fp` | conditional \( x-p \) if \( x\ge p \) |
| `fp_add` | 0 0→0 | `Fp×Fp` → `Fp` | \( (a+b)\bmod p \) |
| `fp_sub` | 0 0→0 | `Fp×Fp` → `Fp` | \( (a-b)\bmod p \) |
| `fp_mul` | 0 0→0 | `Fp×Fp` → `Fp` | mulmod via reduction identity |
| `fp_mulmod` | 0 0→0 | `u64×u64` → `u64` | 128-bit product + fold \( \mathrm{lo}+\mathrm{hi\_lo}\cdot\varepsilon-\mathrm{hi\_hi} \) |
| `fp_pow` | 0 0→0 | `Fp×u64` → `Fp` | square-and-multiply |
| `fp_inv` | 0→0 | `Fp` → `Fp` | \( a^{p-2} \) (Fermat) |
| `fp_add_batch` | 1 1→1 | `FpVec×FpVec` → `FpVec` | elementwise add |
| `fp_mul_batch` | 1 1→1 | `FpVec×FpVec` → `FpVec` | elementwise mul |
---
## Verbs — PMAT
| Verb | Rank | Domain → range | Meaning |
|------|------|----------------|---------|
| `pmat_new` | 0 0→1 | `(rows;cols)` → empty `PMat` | allocate shape |
| `pmat_insert` | 1 0 0 0 1→1 | PMat,row,col,sign,Signature → PMat\|fail | domain checks ±1 and bounds |
| `pmat_validate_grading` | 1→0 | `PMat` → boolean | global grading (stated identity) |
| `pmat_conservation` | 1→1 | `PMat` → `Signature` | Σ monomials |
| `pmat_compose` | 1 1→1 | `PMat×PMat` → `PMat` | sign multiply + monomial accumulate |
| `pmat_frobenius` | 1→0 | `PMat` → real | \( \sqrt{\#entries} \) |
---
## Verbs — Spectral governor
| Verb | Rank | Domain → range | Meaning |
|------|------|----------------|---------|
| `gershgorin_bound` | 2→0 | `Jacobian` → real | max disk \( |J_{ii}|+\sum_{j\neq i}|J_{ij}| \) |
| `gershgorin_check` | 2 0→1 | Jacobian,ε → `SpectralResult` | contractive iff bound \( <1-\varepsilon \) |
| `power_iteration` | 2 0 0→0 | Jacobian,max_iters,tol → real | dominant \|eigenvalue\| |
| `power_iteration_check` | 2 0 0→1 | Jacobian,ε,max_iters → `SpectralResult` | same contractive predicate |
| `spectral_analyze` | 2 0→1 | Jacobian,ε → `SpectralResult` | Gershgorin then optional power iter |
---
## Verbs — Banach recurrence
| Verb | Rank | Domain → range | Meaning |
|------|------|----------------|---------|
| `tier_eps` | 0→0 | `Tier` → real | margin ε |
| `synth_weights` | 0 0 1→2 | max_steps,Tier,profile,[primes] → (Ξ schedule; Λ schedule) | Uniform/Harmonic/LogDecay; 0.7/0.3 of \( q^\star \) |
| `soft_project` | 1 1 0 0→1 1 | Ξ,Λ,q,ε → scaled Ξ,Λ | scale by \( (1-\varepsilon)/q \) if \( q>1-\varepsilon \) |
| `rec_step` | 1 1 1 1→1 1 | x, Ξ, Λ, g ; T ; p_op → (x_next; StepInfo) | \( x'=\Xi x+\Lambda T(x)+g \) then project |
| `rec_run` | 1 0→2 | x0, config, T, p_op → StepInfo history | until residual < tol or max_steps |
| `residual_l2` | 1 1→0 | x_next, x_t → real | \( \|x'-x\|_2 \) |
| `q_estimate` | 1 1 1 1→0 | Ξ,Λ,x,Tx → real | \( \|\Xi\|_\infty+\|\Lambda\|_\infty\cdot\|T\| \) (coded max-abs form) |
Transform `T` and projector `p_op` are rank-1→1 function nouns (hooks), not fixed verbs.
---
## Verbs — Emission / CSL / certify (math-adjacent)
| Verb | Rank | Domain → range | Meaning |
|------|------|----------------|---------|
| `emit_apply` | 1 1 0 0→1 | out,prev,q,policy×ε → out' | PassThrough/Suppress/Hold/Attenuate |
| `csl_neutrality` | 1 1 0→0 | x,Tx,ε → verdict | pairwise Lip-style bound |
| `csl_beneficence` | 1 1 0 0→0 | x,Tx,residual,ε → verdict | norm & residual growth |
| `csl_commutation` | 1 0→0 | x; T; filter; ε → verdict | filter∘T ≈ T∘filter |
| `ace_safety_margin` | 0 0→0 | max_q,ε → real | \( (1-\varepsilon)-\max_q \) |
| `ace_tail_bound` | 0 0→0 | tail_norm,max_q → real | \( \mathrm{tail}/(1-\max_q) \) or ∞ |
| `ace_certify` | 1 0→1 | StepInfo list, delta → `AceCert` | margin ≥ delta |
---
## Coverage map (C++ → J)
| C++ module | J surface |
|------------|-----------|
| `goldilocks.h/cpp` | `fp_*` verbs + `Fp` / `FpVec` |
| `pmat.h/cpp` | `pmat_*` + `Signature` / `PMat` |
| `spectral.h/cpp` | `gershgorin_*` / `power_*` / `spectral_analyze` |
| `recurrence.h/cpp` | `rec_*` / `synth_weights` / `soft_project` / `q_estimate` |
| `types.h` constants | constant nouns + `tier_eps` |
| `gate.h/cpp` (math) | `emit_apply` / `csl_*` |
| `certify.h/cpp` | `ace_*` |
Non-math orchestration (SHA-256 WORM bytes, linker PIRTM, audit JSON) is out of this pure-J math Core inventory except where PROPERTIES.md cites seal-chain / consensus narrative for completeness.
|