Feat/func case ins (#992)

* feat: normalize function names to lowercase for case-insensitive consistency

* test: add tests for case-insensitive namespace and function registration

* refactor: remove `hostfunction` package and migrate functionality to `runtime`

* refactor: switch from canonical to declared function name handling for improved consistency

* test: update namespace casing tests for clarity and consistency

* test: update registry test to use consistent casing for function names

Author: ziflex

compat/compat_test.go

@@ -183,7 +183,7 @@ func TestFunctions_RegisteredFunctions(t *testing.T) {
 	}
 
 	if !found["CUSTOM_A"] || !found["CUSTOM_B"] {
-		t.Fatalf("expected CUSTOM_A and CUSTOM_B in registered functions, got %v", names)
+		t.Fatalf("expected declared CUSTOM_A and CUSTOM_B in registered functions, got %v", names)
 	}
 }
 

compat/compiler/compiler.go

@@ -104,7 +104,7 @@ func (c *Compiler) Namespace(name string) core.Namespace {
 func (c *Compiler) RegisterFunction(name string, fun core.Function) error {
 	fns := c.library.Function()
 	if fns.Has(name) {
-		return nil // already registered — match v1 silent-overwrite semantics
+		return nil
 	}
 
 	fns.Var().Add(name, core.UnwrapFunction(fun))

compat/compiler/compiler_test.go

@@ -45,6 +45,12 @@ func TestCompiler_RegisterFunction(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 
+	if err := c.RegisterFunction("hello", func(context.Context, ...core.Value) (core.Value, error) {
+		return core.WrapValue(runtime.NewString("replacement")), nil
+	}); err != nil {
+		t.Fatalf("case-only duplicate should be silently skipped: %v", err)
+	}
+
 	prog, err := c.Compile(`RETURN HELLO()`)
 	if err != nil {
 		t.Fatalf("compile error: %v", err)
@@ -63,6 +69,57 @@ func TestCompiler_RegisterFunction(t *testing.T) {
 	if result != "hello" {
 		t.Fatalf("expected \"hello\", got %q", result)
 	}
+
+	if got := c.RegisteredFunctions(); len(got) != 1 || got[0] != "HELLO" {
+		t.Fatalf("registered functions = %v, want original HELLO spelling", got)
+	}
+}
+
+func TestCompiler_NamespaceRegistrationIsCaseInsensitive(t *testing.T) {
+	c := compiler.New()
+	ns := c.Namespace("DB").Namespace("POSTGRES")
+
+	err := ns.RegisterFunction("QUERY", func(context.Context, ...core.Value) (core.Value, error) {
+		return core.WrapValue(runtime.NewString("ok")), nil
+	})
+	if err != nil {
+		t.Fatalf("register namespaced function: %v", err)
+	}
+
+	if err := c.Namespace("db").Namespace("postgres").RegisterFunction("query", func(context.Context, ...core.Value) (core.Value, error) {
+		return core.WrapValue(runtime.None), nil
+	}); err == nil {
+		t.Fatal("expected duplicate normalized namespace member to fail")
+	}
+
+	for _, query := range []string{
+		"RETURN db::postgres::query()",
+		"RETURN DB::POSTGRES::QUERY()",
+		"RETURN Db::Postgres::Query()",
+	} {
+		prog, compileErr := c.Compile(query)
+		if compileErr != nil {
+			t.Fatalf("compile %q: %v", query, compileErr)
+		}
+
+		out, runErr := prog.Run(t.Context())
+		if runErr != nil {
+			t.Fatalf("run %q: %v", query, runErr)
+		}
+
+		var result string
+		if err := json.Unmarshal(out, &result); err != nil {
+			t.Fatalf("unmarshal %q output: %v", query, err)
+		}
+
+		if result != "ok" {
+			t.Fatalf("run %q = %q, want ok", query, result)
+		}
+	}
+
+	if got := ns.RegisteredFunctions(); len(got) != 1 || got[0] != "DB::POSTGRES::QUERY" {
+		t.Fatalf("registered functions = %v, want declared qualified name", got)
+	}
 }
 
 func TestCompiler_RegisteredFunctions(t *testing.T) {
@@ -82,7 +139,7 @@ func TestCompiler_RegisteredFunctions(t *testing.T) {
 	}
 
 	if !found["FUNC_A"] || !found["FUNC_B"] {
-		t.Fatalf("expected FUNC_A and FUNC_B, got %v", names)
+		t.Fatalf("expected declared FUNC_A and FUNC_B, got %v", names)
 	}
 }
 
@@ -100,9 +157,9 @@ func TestCompiler_RegisterFunctions_duplicate(t *testing.T) {
 		t.Fatalf("first RegisterFunctions error: %v", err)
 	}
 
-	// Second registration of the same set should be silently skipped (no error).
+	// Second registration of the same set is silently skipped for v1 compatibility.
 	if err := c.RegisterFunctions(fns); err != nil {
-		t.Fatalf("second RegisterFunctions should silently skip duplicates, got: %v", err)
+		t.Fatalf("second RegisterFunctions should skip duplicates: %v", err)
 	}
 
 	// Most importantly: Compile must succeed — no latent builder error must have

compat/runtime/core/functions.go

@@ -141,8 +141,9 @@ func (a *namespaceAdapter) RegisteredFunctions() []string {
 		fns.A4(),
 	} {
 		for _, n := range defs.List() {
-			if _, ok := seen[n]; !ok {
-				seen[n] = struct{}{}
+			key := runtime.NormalizeRegisteredName(n)
+			if _, ok := seen[key]; !ok {
+				seen[key] = struct{}{}
 				names = append(names, n)
 			}
 		}

docs/maintainers/core-api-reference.md

@@ -13,12 +13,17 @@ fixed arity, variadic definition, overload, root function, and nested namespace.
 Unregistered Go declarations are not published.
 
 The generator then loads `pkg/stdlib` source with `go/packages` and resolves each
-registered function to its declaration. The assertion descriptors used by `T`
-and `T::NOT` are resolved statically, including their `Args.Min` and `Args.Max`
+registered function to its declaration. The assertion descriptors used by `t`
+and `t::not` are resolved statically, including their `Args.Min` and `Args.Max`
 bounds. Any unresolved declaration, unsupported registration shape, documentation
 error, arity contradiction, or runtime/source mismatch fails generation without
 writing a partial artifact.
 
+Host-function qualified names are case-insensitive in FQL and have one canonical
+lowercase presentation in the registry and generated API Reference. This includes
+every namespace segment; casing compatibility is represented by lookup rather
+than duplicate aliases.
+
 The API Reference and discovery-index wire contracts belong to
 [`github.com/MontFerret/specs`](https://github.com/MontFerret/specs). Ferret pins
 the released Specs version in the independent generator and publisher modules,
@@ -32,7 +37,7 @@ Registered declarations use the strict structured format parsed by
 `api.ParseDocumentation`:
 
 ```go
-// SPLIT divides a string at each separator.
+// split divides a string at each separator.
 // @param value {String} Source string.
 // @param separator {String} Separator string.
 // @return {String[]} Split values.
@@ -53,7 +58,7 @@ The rules are intentionally strict:
 - Parameters are flat. Describe nested map fields in the parent parameter's
   description instead of using names such as `params.mode`.
 - Assertion descriptor prose is namespace-neutral because the same descriptor
-  documents both positive and `T::NOT` overloads. The descriptor documents its
+  documents both positive and `t::not` overloads. The descriptor documents its
   maximum argument list; each fixed overload receives the corresponding prefix.
 
 Run the focused authoring and parity checks after changing stdlib registration

engine_options.go

@@ -193,6 +193,7 @@ func WithNamespace(ns runtime.Namespace) Option {
 }
 
 // WithFunctionsRegistrar creates an Option that invokes the provided registrar with the engine's runtime.Namespace if the registrar is not nil.
+// Registered host-function names and namespace segments are canonicalized to lowercase and resolve case-insensitively in FQL.
 func WithFunctionsRegistrar(setter func(ns runtime.Namespace)) Option {
 	return func(env *options) error {
 		if setter == nil {

engine_options_test.go

@@ -1,15 +1,19 @@
 package ferret
 
 import (
+	"context"
 	"errors"
+	"slices"
 	"strings"
 	"testing"
 
 	"github.com/MontFerret/ferret/v2/pkg/compiler"
 	ferretnet "github.com/MontFerret/ferret/v2/pkg/net"
 	ferrethttp "github.com/MontFerret/ferret/v2/pkg/net/http"
 	"github.com/MontFerret/ferret/v2/pkg/runtime"
+	"github.com/MontFerret/ferret/v2/pkg/source"
 	"github.com/MontFerret/ferret/v2/pkg/stdlib"
+	"github.com/MontFerret/ferret/v2/pkg/vm"
 )
 
 func mustNewOptionsForTest(t *testing.T, setters ...Option) *options {
@@ -226,6 +230,109 @@ func TestWithStdlibSafeRegistersSelectedGroups(t *testing.T) {
 	}
 }
 
+func TestWithFunctionsRegistrarPreservesQualifiedHostFunctionNames(t *testing.T) {
+	t.Parallel()
+
+	eng := mustNewEngine(t,
+		WithoutStdlib(),
+		WithFunctionsRegistrar(func(ns runtime.Namespace) {
+			ns.Namespace("Tools").Namespace("Risk").Function().A0().Add("Calculate_Risk", func(context.Context) (runtime.Value, error) {
+				return runtime.NewString("ok"), nil
+			})
+		}),
+	)
+	defer func() { _ = eng.Close() }()
+
+	if got := eng.host.functions.List(); !slices.Equal(got, []string{"Tools::Risk::Calculate_Risk"}) {
+		t.Fatalf("expected declared host metadata, got %v", got)
+	}
+
+	for _, query := range []string{
+		"return tools::risk::calculate_risk()",
+		"return TOOLS::RISK::CALCULATE_RISK()",
+		"return Tools::Risk::Calculate_Risk()",
+	} {
+		output, err := eng.Run(t.Context(), source.NewAnonymous(query))
+		if err != nil {
+			t.Fatalf("run %q: %v", query, err)
+		}
+
+		if got := string(output.Content); got != `"ok"` {
+			t.Fatalf("run %q = %s, want %q", query, got, `"ok"`)
+		}
+	}
+}
+
+func TestWithFunctionsRegistrarRejectsCaseOnlyDuplicate(t *testing.T) {
+	t.Parallel()
+
+	eng, err := New(
+		WithoutStdlib(),
+		WithFunctionsRegistrar(func(ns runtime.Namespace) {
+			fn := func(context.Context) (runtime.Value, error) { return runtime.None, nil }
+			ns.Function().A0().Add("foo", fn).Add("FOO", fn)
+		}),
+	)
+	if eng != nil {
+		_ = eng.Close()
+	}
+
+	if err == nil {
+		t.Fatal("expected case-only duplicate registration to fail")
+	}
+}
+
+func TestUnknownHostFunctionDiagnosticPreservesSourceSpelling(t *testing.T) {
+	t.Parallel()
+
+	eng := mustNewEngine(t, WithoutStdlib())
+	defer func() { _ = eng.Close() }()
+
+	const name = "TOOLS::MiSsInG"
+	_, err := eng.Run(t.Context(), source.NewAnonymous("return "+name+"()"))
+	if err == nil {
+		t.Fatal("expected unknown host function to fail")
+	}
+
+	var runtimeErr *vm.RuntimeError
+	if !errors.As(err, &runtimeErr) {
+		t.Fatalf("expected RuntimeError, got %T: %v", err, err)
+	}
+
+	want := "function '" + name + "' is not registered"
+	if got := runtimeErr.Spans[0].Label; got != want {
+		t.Fatalf("diagnostic label = %q, want %q", got, want)
+	}
+}
+
+func TestResolvedHostFunctionDiagnosticUsesRegisteredQualifiedName(t *testing.T) {
+	t.Parallel()
+
+	eng := mustNewEngine(t,
+		WithoutStdlib(),
+		WithFunctionsRegistrar(func(ns runtime.Namespace) {
+			ns.Namespace("DB").Namespace("POSTGRES").Function().A1().Add("QUERY", func(context.Context, runtime.Value) (runtime.Value, error) {
+				return runtime.None, nil
+			})
+		}),
+	)
+	defer func() { _ = eng.Close() }()
+
+	_, err := eng.Run(t.Context(), source.NewAnonymous("return Db::Postgres::Query()"))
+	if err == nil {
+		t.Fatal("expected invalid host function arity to fail")
+	}
+
+	var runtimeErr *vm.RuntimeError
+	if !errors.As(err, &runtimeErr) {
+		t.Fatalf("expected RuntimeError, got %T: %v", err, err)
+	}
+
+	if got, want := runtimeErr.Note, "DB::POSTGRES::QUERY expects 1 argument, but got 0"; got != want {
+		t.Fatalf("diagnostic note = %q, want %q", got, want)
+	}
+}
+
 func TestWithStdlibEmptyMatchesWithoutStdlib(t *testing.T) {
 	t.Parallel()
 

pkg/asm/disassembler_test.go

@@ -517,7 +517,7 @@ func TestDisassemble_HCallCommentMissingWhenNoMatchingLoadConst(t *testing.T) {
 		t.Fatalf("Disassemble() error: %v", err)
 	}
 
-	if strings.Contains(out, "; host X::DO") {
+	if strings.Contains(out, "; host x::do") {
 		t.Fatalf("did not expect host comment when LOADC register does not match HCALL register:\n%s", out)
 	}
 }

pkg/bytecode/artifact/artifact_test.go

@@ -34,8 +34,9 @@ func TestMarshalAndUnmarshal_DefaultMessagePack(t *testing.T) {
 	if got, want := decoded.ISAVersion, program.ISAVersion; got != want {
 		t.Fatalf("unexpected isaVersion: got %d, want %d", got, want)
 	}
-	if !reflect.DeepEqual(decoded.Functions.Host, program.Functions.Host) {
-		t.Fatalf("host signature order mismatch: got %v, want %v", decoded.Functions.Host, program.Functions.Host)
+	expected := artifactHostFunctions()
+	if !reflect.DeepEqual(decoded.Functions.Host, expected) {
+		t.Fatalf("host signature order or spelling mismatch: got %v, want %v", decoded.Functions.Host, expected)
 	}
 }
 
@@ -60,8 +61,9 @@ func TestMarshalAndUnmarshal_JSON(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Unmarshal() error = %v", err)
 	}
-	if !reflect.DeepEqual(decoded.Functions.Host, program.Functions.Host) {
-		t.Fatalf("host signature order mismatch: got %v, want %v", decoded.Functions.Host, program.Functions.Host)
+	expected := artifactHostFunctions()
+	if !reflect.DeepEqual(decoded.Functions.Host, expected) {
+		t.Fatalf("host signature order or spelling mismatch: got %v, want %v", decoded.Functions.Host, expected)
 	}
 }
 
@@ -461,8 +463,8 @@ func newArtifactTestProgram() *bytecode.Program {
 	return &bytecode.Program{
 		Source: source.New("artifact.fql", "RETURN 1"),
 		Functions: bytecode.Functions{Host: []bytecode.HostFunction{
-			{Name: "PICK", ArgCount: 2},
-			{Name: "PICK", ArgCount: 1},
+			{Name: "DB::POSTGRES::PICK", ArgCount: 2},
+			{Name: "Db::Postgres::Pick", ArgCount: 1},
 		}},
 		Bytecode: []bytecode.Instruction{
 			bytecode.NewInstruction(bytecode.OpLoadConst, bytecode.NewRegister(0), bytecode.NewConstant(0)),
@@ -485,6 +487,13 @@ func newArtifactTestProgram() *bytecode.Program {
 	}
 }
 
+func artifactHostFunctions() []bytecode.HostFunction {
+	return []bytecode.HostFunction{
+		{Name: "DB::POSTGRES::PICK", ArgCount: 2},
+		{Name: "Db::Postgres::Pick", ArgCount: 1},
+	}
+}
+
 func TestLoaderRejectsMalformedPayload(t *testing.T) {
 	isaVersion := bytecode.Version
 	registers := 1

pkg/bytecode/format/json/format_test.go

@@ -102,18 +102,22 @@ func TestFormatAllowsOverloadedHostsAndRejectsDuplicateSignaturesAndLabels(t *te
 	one := 1
 	two := 2
 	frame.Functions.Host = []persist.HostFunctionFrame{
-		{Name: "dup", ArgCount: &one},
-		{Name: "dup", ArgCount: &two},
+		{Name: "DB::POSTGRES::DUP", ArgCount: &one},
+		{Name: "db::postgres::dup", ArgCount: &two},
 	}
 
 	data := mustMarshalFrame(t, frame)
-	if _, err := Default.Unmarshal(data); err != nil {
+	decoded, err := Default.Unmarshal(data)
+	if err != nil {
 		t.Fatalf("expected overloaded host signatures to decode, got %v", err)
 	}
+	if got := decoded.Functions.Host[0].Name; got != "DB::POSTGRES::DUP" {
+		t.Fatalf("expected stored host metadata spelling to survive, got %q", got)
+	}
 
 	frame.Functions.Host[1].ArgCount = &one
 	data = mustMarshalFrame(t, frame)
-	_, err := Default.Unmarshal(data)
+	_, err = Default.Unmarshal(data)
 	if !errors.Is(err, bytecode.ErrInvalidProgram) {
 		t.Fatalf("expected ErrInvalidProgram for duplicate host signatures, got %v", err)
 	}