flatsqlrt: take the engine that cannot trap on a SQL error (flatsql b26ed45)

host-01's record catalog had NEVER finished hydrating. Every boot, ~2 min
into the 1,344,427-frame replay:

    [error] execution failed: unreachable, Code: 0x40a
    [error] calling stack:3351, 3351, 3351, 325, 192, 574, 3351
        When executing module name: "flatsql", function name: "flatsql_query_params"
    FlatSQL full record-catalog replay failed after 2m17.389s -> epoch 2

Four hypotheses had already been excluded by measurement (the data, the row
count, AOT, the guest bytecode). The fifth — the runtime pin — is excluded
here too: the real 450 MB journal replays ALL 1,344,427 frames clean under
WasmEdge 0.16.4 on darwin-arm64 (32.1 s) AND under Docker linux/amd64, the
host's exact pin (1479 s emulated), on the unmodified engine.

The axis was none of those. It was the ERROR PATH ITSELF. The engine
artifact is compiled -fignore-exceptions, so `throw` is `unreachable`; a
plain SQL error inside a bound INSERT aborted the guest. flatsql b26ed45
routes every C-ABI query entry through an exception-free path.

Reproduced deterministically in 0.07 s — no 450 MB journal, no host access
— and the fixture is committed: sql_error_no_trap_test.go asserts that
flatsql_query, _query_params, _query_many and _query_template all return a
NAMED SQL error and leave the engine USABLE. Green on darwin-arm64 and in
Docker linux/amd64 WasmEdge 0.16.4.

Engine: 1c53398ae6dc76ec -> 4d17fc5f4936305a, in BOTH embeds (sdn-server
and the kubo mirror) so the two hosts cannot drift on this.

TestAOTCache asserted "exactly one file" in a machine-wide cache that
retains the predecessor artifact on purpose; it now asserts the artifact
for the engine bytes under test is present and the prefix stays inside the
retention bound, so it catches a real cache miss instead of every engine
rebuild.

STILL OPEN, and now VISIBLE for the first time: with the guest no longer
trapping, the replay reports the host-side cause in plain text —

  replay record index batch: flatsqlrt: query_params: SQL execution error:
  UNIQUE constraint failed: sdn_record_index.rowid

reproduced off-host on the real journal at 285,000 frames by
TestReproHost01JournalReplayWithLiveWrites (added here), which replays it
WHILE live traffic publishes — host-01's actual condition and the one axis
the plain repro never covered. replayRowIDState snapshots rowid ownership
ONCE at replay start, but a chunked replay releases the store lock between
windows, so live inserts draw from the same rowid space the replay is
handing out. That is filed as sdn-replay-rowid-collides-with-live-writes;
hydration completes only once both land.

Suites: internal/flatsqlrt, internal/storage (492 s), internal/flatsqldrv,
internal/wasmrt, kubo/sdn/flatsqlrt — all green.

graph task: mod-flatsql-query-params-unreachable-trap (P1)

Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01VBJfFY5kwQjrwuWe3Kw5E7

Author: TJKoury

kubo/sdn/flatsqlrt/README.md

@@ -16,8 +16,8 @@ aligned size-prefixed FlatBuffer frames (`QueryRawFlatBufferStream`).
 `flatsql` repo (superproject submodule `repos/main-packages/flatsql`):
 
 - source path: `flatsql/wasm/flatsql-wasi-noeh.wasm`
-- flatsql commit: `8e86fee` (v1.2.0 — sandboxed public query `flatsql_query_sandboxed`, gateway loop G.5)
-- sha256: `1c53398ae6dc76ec806a3e4724461c6ccc82b6fe8861c6a1a42efcfa4b4c7f64`
+- flatsql commit: `b26ed45` (no-eh query-error latch — a SQL error is a value, never `unreachable`)
+- sha256: `4d17fc5f4936305a005bfc5c63c550a58e448412900299ac7d6adc63ba0137e9`
 
 Why no-exceptions (loop A.3/A.3b findings, measured): WasmEdge's AOT
 compiler (0.14–0.17) cannot parse wasm-exceptions (exnref) modules, and its
@@ -27,12 +27,30 @@ Wasmtime runs exnref natively but its C API/Go bindings do not expose the
 exceptions proposal yet. The no-EH build is export-identical and
 byte-parity-verified against the browser artifact (parity_test.go).
 
-Error semantics (since flatsql A.3c no-throw refactor): user-triggerable
-failures — bad SQL, param-count mismatch, unknown template, duplicate
-source, bad schema — are pre-validated/latched in the engine WITHOUT
-throwing, return clean errors, and do NOT poison the runtime. Only a
-genuine trap (untouched internal throw path, OOM, unreachable) sets
-`Runtime.Poisoned()`; a poisoned runtime must be discarded and recreated.
+Error semantics: EVERY host-reachable query failure is a value, never a
+trap. Two layers get there:
+
+- pre-validation (flatsql A.3c): bad SQL, param-count mismatch, unknown
+  template, duplicate source, bad schema are latched before execution;
+- exception-free EXECUTION (flatsql no-eh query-error latch, graph task
+  `mod-flatsql-query-params-unreachable-trap`): SQL errors raised while the
+  statement RUNS — constraint violations, busy/locked-after-retries, bind
+  and IO errors — return through `executeNoThrow`/`queryNoThrow` instead of
+  `throw`.
+
+The second layer is not cosmetic. This artifact is compiled
+`-fignore-exceptions`, so a `throw` on this build is not an exception, it
+is `unreachable`: the guest aborts and the whole engine instance is
+poisoned. Before the latch, an ordinary UNIQUE-constraint violation inside
+one bound INSERT aborted host-01's record-catalog hydration on every boot
+(`flatsql_query_params`, `calling stack:3351, 3351, 3351, 325, 192, 574,
+3351`), so its 1.34M-frame catalog never finished hydrating. The contract is
+asserted directly by `sql_error_no_trap_test.go` across every query entry
+the C ABI exposes.
+
+Only a genuine trap (a remaining internal throw path, OOM, unreachable)
+sets `Runtime.Poisoned()`; a poisoned runtime must be discarded and
+recreated.
 
 Production daemons should pass `WithPrecompiledAOTCache(dir)`: the portable
 module is AOT-compiled by an explicit release/prewarm step and loaded from

kubo/sdn/flatsqlrt/flatsql-wasi-noeh.wasm

@@ -7,6 +7,7 @@ import (
 	"encoding/binary"
 	"encoding/hex"
 	"os"
+	"strings"
 	"testing"
 )
 
@@ -132,7 +133,7 @@ func newOMMDatabase(t *testing.T, rt *Runtime, name string) *Database {
 func TestEmbeddedArtifact(t *testing.T) {
 	sum := sha256.Sum256(EmbeddedWasm())
 	// Must match the provenance block in README.md.
-	const want = "1c53398ae6dc76ec806a3e4724461c6ccc82b6fe8861c6a1a42efcfa4b4c7f64"
+	const want = "4d17fc5f4936305a005bfc5c63c550a58e448412900299ac7d6adc63ba0137e9"
 	if got := hex.EncodeToString(sum[:]); got != want {
 		t.Fatalf("embedded flatsql-wasi-noeh.wasm sha256 = %s, want %s (update README provenance if the pin moved)", got, want)
 	}
@@ -197,9 +198,31 @@ func TestAOTCache(t *testing.T) {
 	if !rt.AOT() {
 		t.Fatal("expected AOT-compiled runtime (compiler unavailable?)")
 	}
+	// Assert the artifact for the engine bytes UNDER TEST is present, rather
+	// than "exactly one file": the shared dev cache legitimately holds an
+	// artifact per engine build, so a count assertion breaks on every
+	// engine-bytes change instead of catching a real cache miss.
 	entries, err := os.ReadDir(dir)
-	if err != nil || len(entries) != 1 {
-		t.Fatalf("AOT cache dir entries: %v err=%v", entries, err)
+	if err != nil {
+		t.Fatalf("read AOT cache dir: %v", err)
+	}
+	sum := sha256.Sum256(EmbeddedWasm())
+	wantName := "flatsql-" + hex.EncodeToString(sum[:])[:16] + "-we" + RuntimeVersion() + ".aot.wasm"
+	found := false
+	engineArtifacts := 0
+	for _, entry := range entries {
+		if strings.HasPrefix(entry.Name(), "flatsql-") {
+			engineArtifacts++
+		}
+		if entry.Name() == wantName {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("AOT artifact %s missing; cache dir holds %v", wantName, entries)
+	}
+	if engineArtifacts == 0 {
+		t.Fatalf("no engine AOT artifact in %s: %v", dir, entries)
 	}
 
 	// Engine works end-to-end on the compiled artifact.

kubo/sdn/flatsqlrt/flatsqlrt_test.go

@@ -0,0 +1,143 @@
+package flatsqlrt
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+)
+
+// A SQL RUNTIME ERROR IS A RESULT, NEVER A TRAP.
+//
+// graph task mod-flatsql-query-params-unreachable-trap. host-01's
+// record-catalog hydration aborted on every boot with
+//
+//	[error] execution failed: unreachable, Code: 0x40a
+//	[error] calling stack:3351, 3351, 3351, 325, 192, 574, 3351
+//	    When executing module name: "flatsql", function name: "flatsql_query_params"
+//
+// and had therefore NEVER finished hydrating its 1,344,427-frame catalog. The
+// cause was not the journal, the row count, AOT, the guest bytecode or the
+// WasmEdge pin (all measured clean): the engine artifact the servers execute,
+// flatsql-wasi-noeh.wasm, is compiled `-fignore-exceptions`, so
+// SQLiteEngine::execute's `throw std::runtime_error("SQL execution error: ...")`
+// lowered to `unreachable`. The try/catch in flatsql_capi.cpp was dead code on
+// that artifact. Any ordinary constraint violation reaching the guest — which
+// live traffic writing to sdn_record_index during a replay can produce — aborted
+// the guest and poisoned the whole engine.
+//
+// This fixture asserts the ABI contract directly, so the defect cannot come back
+// through a different SQL error class or a different entry point: every
+// host-reachable query entry must return an error and leave the engine USABLE.
+func TestSQLErrorNeverTrapsTheGuest(t *testing.T) {
+	rt, err := New()
+	if err != nil {
+		t.Fatalf("New: %v", err)
+	}
+	defer rt.Close()
+
+	db, err := rt.CreateDatabase(ommTestSchema, "sql-error-no-trap")
+	if err != nil {
+		t.Fatalf("CreateDatabase: %v", err)
+	}
+	if _, err := db.Query(`CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT NOT NULL)`); err != nil {
+		t.Fatalf("create table: %v", err)
+	}
+	if _, err := db.Query(`INSERT INTO t (id, v) VALUES (?, ?)`, 1, "seed"); err != nil {
+		t.Fatalf("seed row: %v", err)
+	}
+
+	cases := []struct {
+		name string
+		want string
+		run  func() error
+	}{
+		{
+			// The host-01 class: the replay assigns explicit rowids into
+			// sdn_record_index, so a rowid that collides with one live traffic
+			// already wrote is a PRIMARY KEY violation on a bound INSERT.
+			name: "flatsql_query_params: rowid/PRIMARY KEY collision",
+			want: "UNIQUE constraint failed",
+			run: func() error {
+				_, err := db.Query(`INSERT INTO t (id, v) VALUES (?, ?)`, 1, "collide")
+				return err
+			},
+		},
+		{
+			name: "flatsql_query_params: NOT NULL violation",
+			want: "NOT NULL constraint failed",
+			run: func() error {
+				_, err := db.Query(`INSERT INTO t (id, v) VALUES (?, ?)`, 2, nil)
+				return err
+			},
+		},
+		{
+			name: "flatsql_query_params: unknown table",
+			want: "no such table",
+			run: func() error {
+				_, err := db.Query(`INSERT INTO missing_table (id) VALUES (?)`, 3)
+				return err
+			},
+		},
+		{
+			name: "flatsql_query: unparameterized statement error",
+			want: "no such table",
+			run: func() error {
+				_, err := db.Query(`INSERT INTO missing_table (id) VALUES (7)`)
+				return err
+			},
+		},
+		{
+			name: "flatsql_query_many: error inside a batch",
+			want: "UNIQUE constraint failed",
+			run: func() error {
+				_, err := db.QueryMany([]QueryRequest{
+					{SQL: `INSERT INTO t (id, v) VALUES (?, ?)`, Params: []interface{}{10, "ok"}},
+					{SQL: `INSERT INTO t (id, v) VALUES (?, ?)`, Params: []interface{}{10, "dup"}},
+				})
+				return err
+			},
+		},
+		{
+			name: "flatsql_query_template: error inside a registered template",
+			want: "UNIQUE constraint failed",
+			run: func() error {
+				if err := db.RegisterQueryTemplate("dup-insert",
+					`INSERT INTO t (id, v) VALUES (?, ?)`, false); err != nil {
+					return fmt.Errorf("register: %w", err)
+				}
+				if _, err := db.QueryTemplate("dup-insert", 20, "first"); err != nil {
+					return fmt.Errorf("first template run: %w", err)
+				}
+				_, err := db.QueryTemplate("dup-insert", 20, "second")
+				return err
+			},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := tc.run()
+			if err == nil {
+				t.Fatalf("expected an error from %s", tc.name)
+			}
+			if strings.Contains(err.Error(), "unreachable") || strings.Contains(err.Error(), "poisoned") {
+				t.Fatalf("GUEST TRAPPED on a plain SQL error (this is the defect): %v", err)
+			}
+			if !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("error %q does not carry the SQL diagnosis %q", err, tc.want)
+			}
+			if rt.Poisoned() {
+				t.Fatalf("engine poisoned by a plain SQL error")
+			}
+			// The engine must still be USABLE afterwards — a trap would have
+			// left it refused for every later caller.
+			res, err := db.Query(`SELECT COUNT(*) FROM t`)
+			if err != nil {
+				t.Fatalf("engine unusable after a SQL error: %v", err)
+			}
+			if len(res.Rows) != 1 {
+				t.Fatalf("SELECT COUNT(*) returned %d rows", len(res.Rows))
+			}
+		})
+	}
+}

kubo/sdn/flatsqlrt/sql_error_no_trap_test.go

@@ -16,8 +16,8 @@ aligned size-prefixed FlatBuffer frames (`QueryRawFlatBufferStream`).
 `flatsql` repo (superproject submodule `repos/main-packages/flatsql`):
 
 - source path: `flatsql/wasm/flatsql-wasi-noeh.wasm`
-- flatsql commit: `8e86fee` (v1.2.0 — sandboxed public query `flatsql_query_sandboxed`, gateway loop G.5)
-- sha256: `1c53398ae6dc76ec806a3e4724461c6ccc82b6fe8861c6a1a42efcfa4b4c7f64`
+- flatsql commit: `b26ed45` (no-eh query-error latch — a SQL error is a value, never `unreachable`)
+- sha256: `4d17fc5f4936305a005bfc5c63c550a58e448412900299ac7d6adc63ba0137e9`
 
 Why no-exceptions (loop A.3/A.3b findings, measured): WasmEdge's AOT
 compiler (0.14–0.17) cannot parse wasm-exceptions (exnref) modules, and its
@@ -27,12 +27,30 @@ Wasmtime runs exnref natively but its C API/Go bindings do not expose the
 exceptions proposal yet. The no-EH build is export-identical and
 byte-parity-verified against the browser artifact (parity_test.go).
 
-Error semantics (since flatsql A.3c no-throw refactor): user-triggerable
-failures — bad SQL, param-count mismatch, unknown template, duplicate
-source, bad schema — are pre-validated/latched in the engine WITHOUT
-throwing, return clean errors, and do NOT poison the runtime. Only a
-genuine trap (untouched internal throw path, OOM, unreachable) sets
-`Runtime.Poisoned()`; a poisoned runtime must be discarded and recreated.
+Error semantics: EVERY host-reachable query failure is a value, never a
+trap. Two layers get there:
+
+- pre-validation (flatsql A.3c): bad SQL, param-count mismatch, unknown
+  template, duplicate source, bad schema are latched before execution;
+- exception-free EXECUTION (flatsql no-eh query-error latch, graph task
+  `mod-flatsql-query-params-unreachable-trap`): SQL errors raised while the
+  statement RUNS — constraint violations, busy/locked-after-retries, bind
+  and IO errors — return through `executeNoThrow`/`queryNoThrow` instead of
+  `throw`.
+
+The second layer is not cosmetic. This artifact is compiled
+`-fignore-exceptions`, so a `throw` on this build is not an exception, it
+is `unreachable`: the guest aborts and the whole engine instance is
+poisoned. Before the latch, an ordinary UNIQUE-constraint violation inside
+one bound INSERT aborted host-01's record-catalog hydration on every boot
+(`flatsql_query_params`, `calling stack:3351, 3351, 3351, 325, 192, 574,
+3351`), so its 1.34M-frame catalog never finished hydrating. The contract is
+asserted directly by `sql_error_no_trap_test.go` across every query entry
+the C ABI exposes.
+
+Only a genuine trap (a remaining internal throw path, OOM, unreachable)
+sets `Runtime.Poisoned()`; a poisoned runtime must be discarded and
+recreated.
 
 Production daemons should pass `WithPrecompiledAOTCache(dir)`: the portable
 module is AOT-compiled by an explicit release/prewarm step and loaded from

sdn-server/internal/flatsqlrt/README.md

@@ -7,6 +7,7 @@ import (
 	"encoding/binary"
 	"encoding/hex"
 	"os"
+	"strings"
 	"testing"
 )
 
@@ -132,7 +133,7 @@ func newOMMDatabase(t *testing.T, rt *Runtime, name string) *Database {
 func TestEmbeddedArtifact(t *testing.T) {
 	sum := sha256.Sum256(EmbeddedWasm())
 	// Must match the provenance block in README.md.
-	const want = "1c53398ae6dc76ec806a3e4724461c6ccc82b6fe8861c6a1a42efcfa4b4c7f64"
+	const want = "4d17fc5f4936305a005bfc5c63c550a58e448412900299ac7d6adc63ba0137e9"
 	if got := hex.EncodeToString(sum[:]); got != want {
 		t.Fatalf("embedded flatsql-wasi-noeh.wasm sha256 = %s, want %s (update README provenance if the pin moved)", got, want)
 	}
@@ -197,9 +198,33 @@ func TestAOTCache(t *testing.T) {
 	if !rt.AOT() {
 		t.Fatal("expected AOT-compiled runtime (compiler unavailable?)")
 	}
+	// The cache retains the current artifact AND its predecessor on purpose
+	// (aotRetainedArtifactsPerPrefix — a rollback must come up AOT, not
+	// silently interpreted), so assert the POLICY, not "exactly one file":
+	// the artifact for the engine bytes under test must be present, and the
+	// prefix must stay inside the retention bound.
 	entries, err := os.ReadDir(dir)
-	if err != nil || len(entries) != 1 {
-		t.Fatalf("AOT cache dir entries: %v err=%v", entries, err)
+	if err != nil {
+		t.Fatalf("read AOT cache dir: %v", err)
+	}
+	sum := sha256.Sum256(EmbeddedWasm())
+	wantName := "flatsql-" + hex.EncodeToString(sum[:])[:16] + "-we" + RuntimeVersion() + ".aot.wasm"
+	found := false
+	engineArtifacts := 0
+	for _, entry := range entries {
+		if strings.HasPrefix(entry.Name(), "flatsql-") {
+			engineArtifacts++
+		}
+		if entry.Name() == wantName {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("AOT artifact %s missing; cache dir holds %v", wantName, entries)
+	}
+	if engineArtifacts > aotRetainedArtifactsPerPrefix {
+		t.Fatalf("engine AOT artifacts = %d, retention bound is %d: %v",
+			engineArtifacts, aotRetainedArtifactsPerPrefix, entries)
 	}
 
 	// Engine works end-to-end on the compiled artifact.