functionalscript 0.43.1 → 0.45.0

package/fjs/sul/level/hash/proof.f.mjs

@@ -0,0 +1,134 @@
+/**
+ * @import { Id } from '../../id/types.ts'
+ * @import { EncodeState } from './types.ts'
+ */
+
+import { assert, assertEq } from '../../../asserts/module.f.mjs'
+import { compress, level3Id } from '../../id/module.f.mjs'
+import { emptyEncodeState, encode } from './module.f.mjs'
+
+/** @typedef {readonly (readonly [Id, Id, Id, boolean])[]} _NodeList */
+
+/** @type {(l: Id, r: Id, m: Id, isSymbol: boolean, s: _NodeList) => _NodeList} */
+const add = (l, r, m, isSymbol, s) => [...s, [l, r, m, isSymbol]]
+const enc = encode(add)
+/** @type {EncodeState<_NodeList>} */
+const initial = emptyEncodeState([])
+
+// Run a complete valid word from a clean state; throws if no output is produced.
+/** @type {(symbols: readonly Id[]) => readonly [Id, _NodeList]} */
+const runWord = symbols => {
+    let state = initial
+    for (const s of symbols) {
+        const [out, newState] = enc(s, state)
+        state = newState
+        if (out !== undefined) { return [out, state[0]] }
+    }
+    throw symbols
+}
+
+// Every stored triple must satisfy m === compress(l, r).
+/** @type {(storage: _NodeList) => void} */
+const verifyStorage = storage => {
+    for (const [l, r, m] of storage) { assertEq(m, compress(l, r)) }
+}
+
+const s0 = level3Id(0n)
+const s1 = level3Id(1n)
+
+export const proof = {
+    // Minimum word [s0, t] with t == s0
+    min_equal: () => {
+        const [out, storage] = runWord([s0, s0])
+        assertEq(out, compress(s0, s0))
+        assertEq(storage.length, 1)
+        verifyStorage(storage)
+    },
+
+    // Minimum word [s0, t] with t > s0
+    min_greater: () => {
+        const [out, storage] = runWord([s0, s1])
+        assertEq(out, compress(s0, s1))
+        assertEq(storage.length, 1)
+        verifyStorage(storage)
+    },
+
+    // All symbols before the terminator return undefined
+    intermediate_undefined: () => {
+        const [r0, st0] = enc(s1, initial)
+        assertEq(r0, undefined)
+        const [r1, st1] = enc(s0, st0)
+        assertEq(r1, undefined)
+        const [r2] = enc(s1, st1)
+        assert(r2 !== undefined)
+    },
+
+    // Three-symbol word [s0, s1, t]: end merges (s0,s1), then create merges (root, t)
+    three_symbol: () => {
+        const [out, storage] = runWord([s1, s0, s0])
+        assertEq(out, compress(compress(s1, s0), s0))
+        assertEq(storage.length, 2)
+        verifyStorage(storage)
+        // first add: merge of the two decreasing-prefix symbols during end
+        assertEq(storage[0][0], s1)
+        assertEq(storage[0][1], s0)
+        // second add: merge of trie root with terminator
+        assertEq(storage[1][0], compress(s1, s0))
+        assertEq(storage[1][1], s0)
+    },
+
+    // Output equals the merged value in the last add call
+    output_is_last_add: () => {
+        const [out, storage] = runWord([s1, s0, s1])
+        assertEq(out, /** @type {_NodeList[number]} */ (storage.at(-1))[2])
+    },
+
+    // Stack is empty after flush; storage is preserved
+    state_reset: () => {
+        const st1 = enc(s0, initial)[1]
+        const [, st2] = enc(s0, st1)
+        assertEq(st2[1].length, 0)
+        assertEq(st2[0].length, 1)
+    },
+
+    // Storage grows across consecutive words (not wiped on flush)
+    storage_accumulates: () => {
+        const st1 = enc(s0, initial)[1]
+        const st2 = enc(s1, st1)[1]   // flush [s0, s1]
+        const st3 = enc(s0, st2)[1]
+        const [, st4] = enc(s0, st3)  // flush [s0, s0]
+        assertEq(st4[0].length, 2)
+        verifyStorage(st4[0])
+    },
+
+    // Two consecutive words encode independently and correctly
+    two_words: () => {
+        const st1 = enc(s0, initial)[1]
+        const [r1, st2] = enc(s1, st1)
+        assertEq(r1, compress(s0, s1))
+        const st3 = enc(s0, st2)[1]
+        const [r2] = enc(s0, st3)
+        assertEq(r2, compress(s0, s0))
+    },
+
+    // Different words produce different hashes
+    non_commutative: () => {
+        const [out1] = runWord([s0, s1])
+        const [out2] = runWord([s1, s0, s1])
+        assert(out1 !== out2)
+    },
+
+    // Trie-internal merges have isSymbol=false; only the terminal merge has isSymbol=true
+    isSymbol_terminal_only: () => {
+        const [, storage] = runWord([s1, s0, s0])
+        assertEq(storage[0][3], false)  // Patricia trie merge
+        assertEq(storage[1][3], true)   // terminal compress(root, t)
+    },
+
+    // Single-step word: no trie merges, exactly one isSymbol=true
+    isSymbol_min_word: () => {
+        const [, storage] = runWord([s0, s0])
+        assertEq(storage.length, 1)
+        assertEq(storage[0][3], true)
+    },
+}

package/fjs/sul/level/hash/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Type-level API for hash-level SUL encoding.
+ *
+ * @module
+ */
+import type { State } from '../../../types/patricia_trie/types.ts';
+import type { Id } from '../../id/types.ts';
+/**
+ * Called once per merge during encoding. `merged = compress(left, right)`.
+ * `isSymbol` is `true` for the terminal `compress(root, t)` that produces the
+ * word-level output symbol, and `false` for Patricia trie internal merges.
+ * Implementations record the triple in a content-addressed store.
+ */
+export type Add<S> = (left: Id, right: Id, merged: Id, isSymbol: boolean, storage: S) => S;
+/**
+ * Streaming state for hash-level encoding.
+ * Wraps the Patricia trie state that accumulates the strictly-decreasing
+ * prefix of the word currently being encoded.
+ */
+export type EncodeState<S> = State<S, Id>;

package/fjs/sul/level/literal/module.f.d.mts

@@ -0,0 +1,57 @@
+/**
+ * Bijective encoding between words of level-k symbols and single symbols of level k+1,
+ * for the first three literal SUL levels. See `./types.ts` for the
+ * `Word`/`EncodeState`/`Level`/`PipelineState`/`LiteralToVec` type-level API.
+ *
+ * @module
+ *
+ * @import { Equal, StateScan } from '../../../types/function/operator/types.ts'
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { EncodeState, Level, LiteralToVec, PipelineState } from './types.ts'
+ */
+import type { Equal, StateScan } from '../../../types/function/operator/types.ts';
+import type { List } from '../../../types/list/types.ts';
+import type { EncodeState, Level, LiteralToVec, PipelineState } from './types.ts';
+/** @type {(s: bigint) => string} */
+export declare const symbolToString: (s: bigint) => string;
+/** @type {(word: List<bigint>) => string} */
+export declare const wordToString: (word: List<bigint>) => string;
+/** @type {Equal<List<bigint>>} */
+export declare const wordEqual: Equal<List<bigint>>;
+/** Initial encoder state: no symbols seen, zero offset. */
+/** @type {EncodeState} */
+export declare const emptyEncodeState: EncodeState;
+/**
+ * Creates a {@link Level} for alphabet size `n = 2^e + 1`.
+ *
+ * The first three levels for a tree starting from a binary alphabet:
+ *
+ * | `e`  | `n`    |
+ * |------|--------|
+ * | `0`  | `2`    |
+ * | `2`  | `5`    |
+ * | `7`  | `0x81` |
+ *
+ * @param {bigint} e `log2(n - 1)`
+ * @returns {Level}
+ */
+export declare const level: (e: bigint) => Level;
+/** Initial state for the three-level literal pipeline. */
+/** @type {PipelineState} */
+export declare const emptyPipelineState: PipelineState;
+/**
+ * Advances the three-level literal pipeline by one bit.
+ * Returns a level-3 symbol whenever the pipeline emits, otherwise `undefined`.
+ *
+ * @type {StateScan<bigint, PipelineState, bigint | undefined>}
+ */
+export declare const pipelineStep: StateScan<bigint, PipelineState, bigint | undefined>;
+/** Decodes a level-1 symbol to its canonical MSB bit vector. */
+/** @type {LiteralToVec} */
+export declare const literal1ToVec: LiteralToVec;
+/** Decodes a level-2 symbol to its canonical MSB bit vector (via level-1 decoding). */
+/** @type {LiteralToVec} */
+export declare const literal2ToVec: LiteralToVec;
+/** Decodes a level-3 symbol to its canonical MSB bit vector (via level-2 and level-1 decoding). */
+/** @type {LiteralToVec} */
+export declare const literal3ToVec: LiteralToVec;

package/fjs/sul/level/literal/module.f.mjs

@@ -0,0 +1,121 @@
+/**
+ * Bijective encoding between words of level-k symbols and single symbols of level k+1,
+ * for the first three literal SUL levels. See `./types.ts` for the
+ * `Word`/`EncodeState`/`Level`/`PipelineState`/`LiteralToVec` type-level API.
+ *
+ * @module
+ *
+ * @import { Equal, StateScan } from '../../../types/function/operator/types.ts'
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { EncodeState, Level, LiteralToVec, PipelineState } from './types.ts'
+ */
+
+import { log2 } from '../../../types/bigint/module.f.mjs'
+import { msb, vec } from '../../../types/bit_vec/module.f.mjs'
+import { strictEqual } from '../../../types/function/operator/module.f.mjs'
+import { equal, map } from '../../../types/list/module.f.mjs'
+import { join } from '../../../types/string/module.f.mjs'
+
+/** @type {(s: bigint) => string} */
+export const symbolToString = s => s.toString(16)
+
+/** @type {(word: List<bigint>) => string} */
+export const wordToString = word =>
+    join(',')(map(symbolToString)(word))
+
+/** @type {Equal<List<bigint>>} */
+export const wordEqual = equal(strictEqual)
+
+/** Initial encoder state: no symbols seen, zero offset. */
+/** @type {EncodeState} */
+export const emptyEncodeState = [undefined, 0n]
+
+/**
+ * Creates a {@link Level} for alphabet size `n = 2^e + 1`.
+ *
+ * The first three levels for a tree starting from a binary alphabet:
+ *
+ * | `e`  | `n`    |
+ * |------|--------|
+ * | `0`  | `2`    |
+ * | `2`  | `5`    |
+ * | `7`  | `0x81` |
+ *
+ * @param {bigint} e `log2(n - 1)`
+ * @returns {Level}
+ */
+export const level = e => {
+    // m = n - 1
+    const m = 1n << e
+    const n = m + 1n
+    // k = n - 2
+    const k = m - 1n
+    // m2 = 2 * m
+    const m2 = m << 1n
+    const e1 = e + 1n
+    const sum = (/** @type {bigint} */ i) => (m2 << i) + i - k
+    /** @type {(i: bigint) => List<bigint>} */
+    const decode = i => () => {
+        const r = log2((i + k) >> e1)
+        const s0 = sum(r) > i ? r : r + 1n
+        const s1 = i - sum(s0) + n
+        return s1 >= s0 ? [s0, s1] : {
+            first: s0,
+            tail: decode(i - sum(s0 - 1n))
+        }
+    }
+    return {
+        sum,
+        decode,
+        encode: (i, [last, part]) => last === undefined ? [undefined, [i, 0n]] :
+            last > i ? [undefined, [i, part + sum(last - 1n)]] :
+            [part + sum(last) + i - n, emptyEncodeState]
+    }
+}
+
+const l1 = level(0n)
+const l2 = level(2n)
+const l3 = level(7n)
+
+/** Initial state for the three-level literal pipeline. */
+/** @type {PipelineState} */
+export const emptyPipelineState = [emptyEncodeState, emptyEncodeState, emptyEncodeState]
+
+/**
+ * Advances the three-level literal pipeline by one bit.
+ * Returns a level-3 symbol whenever the pipeline emits, otherwise `undefined`.
+ *
+ * @type {StateScan<bigint, PipelineState, bigint | undefined>}
+ */
+export const pipelineStep =
+    (bit, [l1s, l2s, l3s]) => {
+        const [l1Out, newL1s] = l1.encode(bit, l1s)
+        if (l1Out === undefined) return [undefined, [newL1s, l2s, l3s]]
+        const [l2Out, newL2s] = l2.encode(l1Out, l2s)
+        if (l2Out === undefined) return [undefined, [newL1s, newL2s, l3s]]
+        const [l3Out, newL3s] = l3.encode(l2Out, l3s)
+        return [l3Out, [newL1s, newL2s, newL3s]]
+    }
+
+const vec1 = vec(1n)
+
+const { listToVec } = msb
+
+/** @type {(prior: LiteralToVec, e: bigint) => LiteralToVec} */
+const literalToVec = (prior, e) => {
+    const m = map(prior)
+    const { decode } = level(e)
+    return literal => listToVec(m(decode(literal)))
+}
+
+/** Decodes a level-1 symbol to its canonical MSB bit vector. */
+/** @type {LiteralToVec} */
+export const literal1ToVec = literalToVec(vec1, 0n)
+
+/** Decodes a level-2 symbol to its canonical MSB bit vector (via level-1 decoding). */
+/** @type {LiteralToVec} */
+export const literal2ToVec = literalToVec(literal1ToVec, 2n)
+
+/** Decodes a level-3 symbol to its canonical MSB bit vector (via level-2 and level-1 decoding). */
+/** @type {LiteralToVec} */
+export const literal3ToVec = literalToVec(literal2ToVec, 7n)

package/fjs/sul/level/literal/proof.f.d.mts

@@ -0,0 +1,15 @@
+/**
+ * @import { Vec } from '../../../types/bit_vec/types.ts'
+ */
+export declare const proof: {
+    x2: () => void;
+    x5: () => void;
+    x81: () => void;
+    toVec: {
+        level1: () => void;
+        level2: () => void;
+        level3: () => void;
+    };
+    wordToString: () => void;
+    pipeline: () => void;
+};