feat(ml): Engram hash port — the portable address contract

src/ml/imf/engram.ts

@@ -0,0 +1,49 @@
+/**
+ * Engram address hashing — the TypeScript side of the portable
+ * contract (TODO.impl/10 export probe): the hash must produce
+ * IDENTICAL addresses to ml-models src/gpu/engram.py, because
+ * addresses are an IMF graph input computed per runtime. The fixture
+ * in test/fixtures/engram-addresses.json is generated from the Python
+ * implementation; the parity test pins this port to it.
+ */
+
+export const FNV_OFFSET = 0x811c9dc5
+export const FNV_PRIME = 0x01000193
+export const DEFAULT_ORDERS = [2, 3, 4] as const
+
+function fnv1a(data: readonly number[], seed: number): number {
+  let h = (FNV_OFFSET ^ seed) >>> 0
+  for (const b of data) {
+    // Math.imul: 32-bit multiply — plain * exceeds 2^53 and loses
+    // low bits the hash depends on
+    h = Math.imul(h ^ b, FNV_PRIME) >>> 0
+  }
+  return h >>> 0
+}
+
+/** Addresses for the byte n-grams ENDING at each position, hashed as
+ * (id - 3) mod 256 — the canonical byte table. Positions without a
+ * full n-gram address 0 (the null row). */
+export function ngramAddresses(
+  seq: readonly number[],
+  orders: readonly number[] = DEFAULT_ORDERS,
+): number[][] {
+  const out: number[][] = []
+  for (let end = 0; end < seq.length; end++) {
+    const row: number[] = []
+    for (const order of orders) {
+      if (end + 1 >= order) {
+        const gram: number[] = []
+        for (let i = end + 1 - order; i <= end; i++) {
+          gram.push((seq[i]! - 3) & 0xff)
+        }
+        const h = fnv1a(gram, orders.indexOf(order) + 1)
+        row.push(h === 0 ? 1 : h)
+      } else {
+        row.push(0)
+      }
+    }
+    out.push(row)
+  }
+  return out
+}

src/ml/imf/index.ts

@@ -1,6 +1,7 @@
 /** @interscript/ml — the IMF v1 runtime for TypeScript. */
 
 export { IMFModel, type DecodeOptions } from "./model.js"
+export { ngramAddresses, DEFAULT_ORDERS } from "./engram.js"
 export {
   SpeculativeModel,
   acceptBlock,

test/engram-addresses.test.ts

@@ -0,0 +1,25 @@
+/**
+ * Engram hash parity: the TS port must produce identical addresses to
+ * the Python reference (they feed the same IMF graph input). The
+ * fixture is generated from ml-models src/gpu/engram.py.
+ */
+import { readFileSync } from "node:fs"
+import { describe, expect, it } from "vitest"
+import { ngramAddresses } from "../src/ml/imf/engram.js"
+
+const fixture = JSON.parse(readFileSync("test/fixtures/engram-addresses.json", "utf8")) as {
+  orders: number[]
+  cases: { seq: number[]; addresses: number[][] }[]
+}
+
+describe("engram address parity with the Python reference", () => {
+  for (const c of fixture.cases) {
+    it(`matches on seq len ${c.seq.length}`, () => {
+      expect(ngramAddresses(c.seq, fixture.orders)).toEqual(c.addresses)
+    })
+  }
+
+  it("wraps ids through the byte table (id 259+3k ≡ id 3k... byte wrap)", () => {
+    expect(ngramAddresses([103 + 256, 104 + 256])[1]).toEqual(ngramAddresses([103, 104])[1])
+  })
+})

test/fixtures/engram-addresses.json

@@ -0,0 +1 @@
+{"orders": [2, 3, 4], "cases": [{"seq": [117, 114, 110, 1], "addresses": [[0, 0, 0], [1112675351, 0, 0], [1580624302, 1278433265, 0], [3544194105, 1502810677, 223498728]]}, {"seq": [199, 218, 213, 32, 199, 218, 205, 32, 199, 216, 199, 205, 1], "addresses": [[0, 0, 0], [2827990901, 0, 0], [4122765537, 1260683368, 0], [851777453, 1414361537, 3398667802], [3450325389, 3122495958, 1985234714], [2827990901, 2289030571, 2132084646], [3720102681, 858020512, 3420616982], [4071697205, 3565736553, 2323620258], [3450325389, 1656663534, 2667040690], [2794435663, 2322585809, 1706586472], [2612485637, 3978260288, 434598158], [2609881854, 2113218068, 1980499271], [3484583708, 691082965, 1872299291]]}, {"seq": [5], "addresses": [[0, 0, 0]]}, {"seq": [0, 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, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199, 200, 201, 202, 203, 204, 205, 206, 207, 208, 209, 210, 211, 212, 213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 249, 250, 251, 252, 253, 254, 255], "addresses": [[0, 0, 0], [3524979871, 0, 0], [3508452515, 2405554493, 0], [2485164851, 962593764, 1701312898], [3967033079, 2795518203, 569100138], [259429543, 2759583498, 1331757190], [913903779, 1083357929, 665705942], [1501267539, 3567878704, 2478725762], [1483357087, 2025874087, 588507898], [2070720847, 1022033206, 3221394430], [2590974131, 2968390245, 2137782206], [3178337891, 1830328412, 2862493410], [612892375, 960708483, 2853928730], [1200256135, 1671274882, 103539350], [1586288467, 263491217, 2043042854], [2173652227, 66255976, 1174306658], [2155741775, 2550776751, 1939322666], [2743105535, 1815377774, 1890453182], [3263358819, 2148523533, 3783561022], [3850722579, 1278903604, 186782786], [1016835159, 2554155883, 2349612458], [2141082727, 1119850074, 2799123494], [2795556963, 2133163257, 2298790742], [2846036915, 322716736, 406771362], [2828126463, 4144224151, 3880065530], [3952374031, 2071838534, 22628126], [3935743507, 1328656821, 597488734], [765023779, 2880133740, 200610914], [1957661751, 3079058547, 781974330], [3081909319, 2721080210, 1736624150], [2931057843, 2918725089, 502749382], [4055305411, 1116061304, 3875936194], [4037394959, 374159519, 399029194], [4087874911, 2865183102, 2986654174], [850044707, 3198328861, 584794718], [1974292275, 3934137476, 1819867586], [2361604535, 2535416475, 1293158506], [2948968295, 3775083946, 2811214278], [382242851, 4256736201, 2858107926], [4190806291, 288411856, 2629784258], [4172895839, 3041374535, 3960766074], [465292303, 3121643862, 2298685310], [2059313203, 773033605, 35216894], [2646676963, 1772061244, 2897017570], [81231447, 1976208931, 3004987226], [668595207, 1613007714, 3475797526], [4275827219, 1278991665, 3257423206], [568223683, 2165866632, 2388687010], [550313231, 355420111, 3047614442], [2211444607, 2830878222, 1924977342], [2731697891, 1026934509, 1680995710], [2245294035, 3378514260, 337841282], [485174231, 3569656331, 342793130], [535654183, 3219460730, 2833647654], [2263896035, 1011574233, 196225430], [2314375987, 1338217184, 441295522], [2296465535, 1948867511, 3914589690], [2346945487, 4171449190, 173686622], [2330314963, 2344157269, 2885636702], [233362851, 2821866572, 235135074], [352233207, 883701907, 816498490], [2550248391, 2662813042, 813915030], [2399396915, 723368449, 3768918982], [2449876867, 3215671960, 1869116866], [2431966415, 1389659967, 3771287370], [2482446367, 3880683550, 4094945950], [318383779, 2076739837, 3850964318], [1442631347, 654670628, 4118358146], [735387639, 319271483, 1433771242], [1322751399, 2876117834, 4131683206], [1977225635, 1179103913, 2723301334], [417157331, 3663624688, 2176608770], [399246879, 2121620071, 519459578], [986610639, 1138567542, 3152346110], [1506863923, 3084924581, 1835665214], [2094227683, 1946862748, 412944354], [1676214231, 3224674883, 2551811738], [2263577991, 1787809218, 1948957590], [502178259, 2527457617, 1740925862], [1089542019, 2309434024, 3019724898], [1071631567, 498987503, 1849485994], [1658995327, 1911123758, 3948048574], [2179248611, 117522637, 3502232382], [619077139, 3542870004, 96946114], [2080157015, 523154987, 4195030698], [1056972519, 3383816474, 2517794854], [1711446755, 102162361, 2017462102], [1761926707, 2586683136, 125442722], [1744016255, 2092434903, 3790228858], [720728591, 20049286, 4015478430], [704098067, 1424402805, 528440414], [1828345635, 828344492, 131562594], [873551543, 3195592883, 500645690], [1997799111, 669290962, 1667575830], [1846947635, 3035259425, 2348167622], [823659971, 1232595640, 3806887874], [805749519, 2638125919, 2244447434], [856229471, 834182206, 557893470], [1913366563, 3294074845, 494958046], [890182067, 1882348228, 3686074178], [1277494327, 483627227, 3371542250], [1864858087, 1723294698, 2721377606], [1445564707, 57514889, 2768271254], [959160851, 2552378256, 2560735938], [941250399, 1010373639, 1511217018], [1528614159, 3238178198, 4144103550], [975202995, 889567941, 1880635134], [1562566755, 4015239292, 447468514], [1144553303, 2071954915, 2935938906], [1731917063, 3856185762, 3406749206], [1044181779, 1374737649, 3188374886], [1631545539, 114077384, 172103458], [1613635087, 2598598159, 810242538], [1127334399, 799877326, 3982572734], [1647587683, 3290900909, 3547202302], [1161183827, 1347513364, 56512642], [1548496087, 3665402315, 273744810], [1598976039, 1188459834, 2552319014], [1179785827, 3275540633, 2062432022], [1230265779, 1433963168, 159966882], [1212355327, 4192045559, 3824753018], [1262835279, 2119659942, 104638302], [1246204755, 313156373, 436087646], [1296684707, 2938400908, 166086754], [1415555063, 1000236243, 535169850], [1466138183, 2779347378, 2659333270], [1315286707, 839902785, 1319369926], [1365766659, 3332206296, 3714535106], [1347856207, 1485405951, 3702239050], [1398336159, 3976429534, 3813617310], [1381705635, 2172485821, 3761127646], [358521139, 771204964, 1881089410], [1798812663, 2562449531, 1173230954], [2386073255, 2951075466, 1511430534], [3040650659, 1316426601, 61575126], [3627911251, 3759370672, 2299052418], [3610000799, 2258942759, 25850618], [4197467727, 1254998710, 3041721086], [422650547, 3159882213, 1958005694], [1010117475, 2063293916, 2299939298], [2739536087, 1152200451, 2674255386], [3327003015, 1904240386, 3794375830], [3712932179, 454880017, 1904843046], [5431811, 299221480, 611649378], [4282488655, 2742165551, 1759546154], [574781951, 2048343278, 1327795902], [1095138403, 2381489037, 3179430206], [1682502163, 1470395572, 3919195970], [3143582039, 2787121387, 1787058346], [4267726439, 1311342042, 2619346982], [627336547, 2366128761, 1694556758], [677713331, 514105536, 268571554], [659802879, 82325527, 3317408250], [1784050447, 2263330502, 4179395614], [1767523091, 1561622325, 34934622], [2891667491, 3071625708, 62411106], [4084305463, 3270447347, 643774522], [913688903, 2912572178, 1556847638], [762734259, 3110217057, 323076038], [1886981827, 1349026808, 3737736386], [1869071375, 565651487, 260829386], [1919654495, 3098251774, 2423996894], [2976688419, 3389717661, 446698078], [4101039155, 4167102980, 1257210306], [193384119, 2726805275, 1154958698], [780644711, 4008049450, 2248660166], [2508886563, 153157705, 2719908118], [2022585875, 479800656, 2025550274], [2004675423, 3274340039, 3356635258], [2591936015, 3313135830, 2160485502], [4186060083, 1005999109, 3767630078], [478353379, 1963553212, 2717344226], [2207978327, 2209277603, 2400753242], [2795238919, 1804499682, 3296021014], [2107606803, 1511957169, 2694869094], [2694867395, 2357358600, 2250487202], [2676956943, 588488783, 2485060330], [43224191, 3063946894, 1745200830], [563374307, 1218426477, 1542795902], [77073619, 3611479764, 4070254466], [2611817943, 3761045131, 204696490], [2662401063, 3452426234, 2270990374], [95572451, 1203066201, 58128790], [146155571, 1571182688, 4132028834], [128245119, 2140256311, 3734813178], [178621903, 109447398, 3906099806], [162094547, 2577225941, 2281505886], [2360109731, 3013358540, 3925868386], [2478980087, 1116770579, 212264506], [381924807, 2854305010, 675818390], [231176499, 956333953, 3206364870], [281553283, 3407163928, 1689340354], [263642831, 1622728639, 3208733258], [314225951, 4072175518, 3915272606], [2445130659, 2309808509, 3246833502], [3569275059, 887636132, 3938684802], [2862134519, 510660283, 1254097898], [3449395111, 3109083338, 3569025926], [4103972515, 1412172585, 2119170518], [2543904211, 3855116656, 1613951490], [2525993759, 2354688743, 4251769594], [3113254351, 1330059510, 2972672766], [3633610803, 3317890085, 1273111102], [4220871395, 2138354716, 233271010], [3802857943, 3457640387, 1989154458], [95357575, 1979301186, 1810860950], [2628925139, 2760526289, 1136795046], [3216185731, 2542399528, 2839948386], [3198275279, 690376303, 1669812650], [3785742207, 2144089262, 3385391294], [10925027, 309014605, 3364135742], [2745824019, 3775835508, 3829256130], [4206903895, 714646955, 4015357354], [3183719399, 3616781978, 1955137574], [3838090467, 293654329, 1879262294], [3888673587, 2819751808, 3816176034], [3870763135, 2325503575, 3227674746], [2847372303, 211541254, 3411347614], [2830844947, 1657368309, 4260853598], [3954989347, 1019836460, 4288330082], [3000298423, 3428661555, 4191379002], [4124442823, 860782930, 1487799318], [3973694515, 3268224929, 1785613510], [2950303683, 1424087608, 3668688066], [2932393231, 2871091423, 1640213450], [2982976351, 1025571006, 378220126], [4040010275, 3485463645, 356758238], [3016825779, 2115313732, 3506400834], [3404138039, 675016027, 3233445610], [3991604967, 1956260202, 2158720326], [3572208419, 248903689, 2630174614], [3085907731, 2785446928, 1956501954], [3067997279, 1201865607, 1373120378], [3655257871, 3471143702, 3539869566], [3101846707, 1081059909, 1700961790], [3689313635, 4206731260, 4179881698], [3271300183, 2305023587, 2331704922], [3858560775, 4047677730, 3226972694], [3170928659, 1607703153, 2625820774], [3758189251, 305569352, 34006818], [3740278799, 2831666831, 247688426], [3253978111, 991266126, 3802796222], [3774334563, 3523866413, 2943071486], [3287827539, 1539005332, 4171806594], [3675139799, 3856791115, 135648170], [3725722919, 1379951802, 2372542502], [3306532707, 3508506137, 1458198038], [3356909491, 1666928672, 21767074], [3338999039, 88467063, 3645079674], [3389582159, 2352625446, 3837051486], [3372848467, 504545173, 297991006], [3423431587, 3171366412, 3856820066], [3542301943, 1191625043, 396970042], [3592885063, 3012312882, 2055202454], [3441930419, 1031394753, 1139696582], [3492513539, 3565171800, 3151877826]]}]}