space-data-module-sdk 0.8.21 → 0.8.23

package/src/host/flatsqlIoConformance.js

@@ -0,0 +1,349 @@
+// One `flatsql_io` conformance script for every host (docs/architecture/
+// flatsql-partition-store.md 22.3a-6: "Run one flatsql_io conformance script on
+// all three hosts").
+//
+// It drives a provider through the contract's observable behaviour: statuses,
+// short reads, sparse writes, truncation both ways, flag semantics (EXCL,
+// TRUNC, PROBE, UNLINK, UNLINK_IF_UNUSED, CREATE_PARENTS, DELETE_ON_CLOSE,
+// OPEN_DEFERRED), access modes, confinement and multi-handle visibility. The
+// same cases run against the Node sync-fs provider, the SAB channel over the
+// memory backend, and the SAB channel over OPFS in real browsers; a host that
+// differs fails by name.
+//
+// A provider for this script exposes (sync or async; every call is awaited):
+//   open(path: string | Uint8Array, flags) -> handle | status
+//   readInto(handle, view: Uint8Array, offset) -> count | status
+//   writeFrom(handle, view: Uint8Array, offset) -> count | status
+//   truncate(handle, size) / sync(handle) / close(handle) -> status
+//   size(handle) -> number | status
+
+import {
+  FLATSQL_IO_CREATE,
+  FLATSQL_IO_CREATE_PARENTS,
+  FLATSQL_IO_DELETE_ON_CLOSE,
+  FLATSQL_IO_ERR_ACCESS,
+  FLATSQL_IO_ERR_BADHANDLE,
+  FLATSQL_IO_ERR_BUSY,
+  FLATSQL_IO_ERR_GENERIC,
+  FLATSQL_IO_ERR_IO,
+  FLATSQL_IO_ERR_NOENT,
+  FLATSQL_IO_EXCL,
+  FLATSQL_IO_OPEN_DEFERRED,
+  FLATSQL_IO_PROBE,
+  FLATSQL_IO_READ,
+  FLATSQL_IO_TRUNC,
+  FLATSQL_IO_UNLINK,
+  FLATSQL_IO_UNLINK_IF_UNUSED,
+  FLATSQL_IO_WRITE,
+} from "./flatsqlIoContract.js";
+
+const RW = FLATSQL_IO_READ | FLATSQL_IO_WRITE;
+const RWC = RW | FLATSQL_IO_CREATE;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function pattern(length, seed) {
+  const bytes = new Uint8Array(length);
+  let x = seed >>> 0 || 1;
+  for (let i = 0; i < length; i += 1) {
+    x ^= x << 13;
+    x ^= x >>> 17;
+    x ^= x << 5;
+    bytes[i] = x & 0xff;
+  }
+  return bytes;
+}
+
+function equalBytes(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+class ConformanceFailure extends Error {}
+
+function expect(condition, message) {
+  if (!condition) throw new ConformanceFailure(message);
+}
+
+function expectStatus(actual, expected, what) {
+  expect(actual === expected, `${what}: expected ${expected}, got ${actual}`);
+}
+
+function expectHandle(actual, what) {
+  expect(Number.isInteger(actual) && actual >= 0, `${what}: expected a handle, got ${actual}`);
+}
+
+/**
+ * The cases, in order. Each gets `(io, dir)` where `dir` is a fresh directory
+ * prefix for the case.
+ */
+export const FLATSQL_IO_CONFORMANCE_CASES = Object.freeze([
+  {
+    name: "open without CREATE on a missing file is NOENT",
+    async run(io, dir) {
+      expectStatus(await io.open(`${dir}/missing.bin`, RW), FLATSQL_IO_ERR_NOENT, "open");
+    },
+  },
+  {
+    name: "create, write, size, short read at EOF, read past EOF",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/a.bin`, RWC);
+      expectHandle(h, "open");
+      expectStatus(await io.writeFrom(h, encoder.encode("hello"), 0), 5, "write");
+      expectStatus(await io.size(h), 5, "size");
+      const buf = new Uint8Array(10);
+      expectStatus(await io.readInto(h, buf, 0), 5, "short read");
+      expect(decoder.decode(buf.subarray(0, 5)) === "hello", "short read bytes");
+      expectStatus(await io.readInto(h, new Uint8Array(4), 5), 0, "read at EOF");
+      expectStatus(await io.readInto(h, new Uint8Array(4), 100), 0, "read past EOF");
+      expectStatus(await io.close(h), 0, "close");
+    },
+  },
+  {
+    name: "a write past EOF extends the file and the gap reads as zeros",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/sparse.bin`, RWC);
+      expectHandle(h, "open");
+      expectStatus(await io.writeFrom(h, encoder.encode("ab"), 0), 2, "write head");
+      expectStatus(await io.writeFrom(h, encoder.encode("z"), 100), 1, "write past EOF");
+      expectStatus(await io.size(h), 101, "size");
+      const gap = new Uint8Array(98);
+      gap.fill(0xee);
+      expectStatus(await io.readInto(h, gap, 2), 98, "read gap");
+      expect(gap.every((b) => b === 0), "gap is zeros");
+      expectStatus(await io.close(h), 0, "close");
+    },
+  },
+  {
+    name: "truncate shrinks and grows; grown bytes read as zeros",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/t.bin`, RWC);
+      expectHandle(h, "open");
+      await io.writeFrom(h, encoder.encode("abcdefgh"), 0);
+      expectStatus(await io.truncate(h, 3), 0, "truncate down");
+      expectStatus(await io.size(h), 3, "size after shrink");
+      expectStatus(await io.truncate(h, 10), 0, "truncate up");
+      expectStatus(await io.size(h), 10, "size after grow");
+      const buf = new Uint8Array(10);
+      expectStatus(await io.readInto(h, buf, 0), 10, "read");
+      expect(decoder.decode(buf.subarray(0, 3)) === "abc", "kept prefix");
+      expect(buf.subarray(3).every((b) => b === 0), "grown tail is zeros");
+      expectStatus(await io.sync(h), 0, "sync");
+      expectStatus(await io.close(h), 0, "close");
+    },
+  },
+  {
+    name: "closed and bogus handles are BADHANDLE",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/c.bin`, RWC);
+      expectHandle(h, "open");
+      expectStatus(await io.close(h), 0, "close");
+      expectStatus(await io.close(h), FLATSQL_IO_ERR_BADHANDLE, "close again");
+      expectStatus(await io.readInto(h, new Uint8Array(1), 0), FLATSQL_IO_ERR_BADHANDLE, "read");
+      expectStatus(await io.size(0x7fff00), FLATSQL_IO_ERR_BADHANDLE, "bogus size");
+    },
+  },
+  {
+    name: "PROBE reports existence without a handle",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/p.bin`, RWC);
+      expectHandle(h, "open");
+      await io.close(h);
+      expectStatus(await io.open(`${dir}/p.bin`, FLATSQL_IO_PROBE), 0, "probe existing");
+      expectStatus(await io.open(`${dir}/nope.bin`, FLATSQL_IO_PROBE), FLATSQL_IO_ERR_NOENT, "probe missing");
+    },
+  },
+  {
+    name: "EXCL on an existing file is GENERIC; TRUNC empties it",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/x.bin`, RWC);
+      expectHandle(h, "open");
+      await io.writeFrom(h, encoder.encode("data"), 0);
+      await io.close(h);
+      expectStatus(
+        await io.open(`${dir}/x.bin`, RWC | FLATSQL_IO_EXCL),
+        FLATSQL_IO_ERR_GENERIC,
+        "EXCL",
+      );
+      const t = await io.open(`${dir}/x.bin`, RW | FLATSQL_IO_TRUNC);
+      expectHandle(t, "TRUNC open");
+      expectStatus(await io.size(t), 0, "size after TRUNC");
+      await io.close(t);
+    },
+  },
+  {
+    name: "CREATE under a missing directory is NOENT; CREATE_PARENTS makes it",
+    async run(io, dir) {
+      expectStatus(
+        await io.open(`${dir}/p/00000001/h.fsh`, RWC),
+        FLATSQL_IO_ERR_NOENT,
+        "no parents",
+      );
+      const h = await io.open(`${dir}/p/00000001/h.fsh`, RWC | FLATSQL_IO_CREATE_PARENTS);
+      expectHandle(h, "CREATE_PARENTS");
+      expectStatus(await io.writeFrom(h, encoder.encode("head"), 0), 4, "write");
+      await io.close(h);
+      expectStatus(await io.open(`${dir}/p/00000001/h.fsh`, FLATSQL_IO_PROBE), 0, "probe");
+    },
+  },
+  {
+    name: "UNLINK_IF_UNUSED is BUSY while a handle is open; UNLINK removes",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/u.bin`, RWC);
+      expectHandle(h, "open");
+      expectStatus(
+        await io.open(`${dir}/u.bin`, FLATSQL_IO_UNLINK_IF_UNUSED),
+        FLATSQL_IO_ERR_BUSY,
+        "unlink while open",
+      );
+      await io.close(h);
+      expectStatus(await io.open(`${dir}/u.bin`, FLATSQL_IO_UNLINK_IF_UNUSED), 0, "unlink unused");
+      expectStatus(await io.open(`${dir}/u.bin`, FLATSQL_IO_PROBE), FLATSQL_IO_ERR_NOENT, "gone");
+      expectStatus(await io.open(`${dir}/u.bin`, FLATSQL_IO_UNLINK), FLATSQL_IO_ERR_NOENT, "unlink missing");
+      const again = await io.open(`${dir}/v.bin`, RWC);
+      await io.close(again);
+      expectStatus(await io.open(`${dir}/v.bin`, FLATSQL_IO_UNLINK), 0, "plain unlink");
+    },
+  },
+  {
+    name: "DELETE_ON_CLOSE drops the file with its last handle",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/tmp.bin`, RWC | FLATSQL_IO_DELETE_ON_CLOSE);
+      expectHandle(h, "open");
+      await io.writeFrom(h, encoder.encode("scratch"), 0);
+      expectStatus(await io.close(h), 0, "close");
+      // Hosts that delete asynchronously finish before the next namespace op.
+      expectStatus(await io.open(`${dir}/tmp.bin`, FLATSQL_IO_PROBE), FLATSQL_IO_ERR_NOENT, "probe");
+    },
+  },
+  {
+    name: "paths are confined below the root",
+    async run(io, dir) {
+      expectStatus(await io.open(`${dir}/../../escape.bin`, RWC), FLATSQL_IO_ERR_ACCESS, "..");
+      expectStatus(await io.open("", RWC), FLATSQL_IO_ERR_GENERIC, "empty path");
+    },
+  },
+  {
+    name: "access modes: read-only handles refuse writes, write-only refuse reads",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/m.bin`, RWC);
+      await io.writeFrom(h, encoder.encode("mode"), 0);
+      await io.close(h);
+      const ro = await io.open(`${dir}/m.bin`, FLATSQL_IO_READ);
+      expectHandle(ro, "read-only open");
+      expectStatus(await io.writeFrom(ro, encoder.encode("x"), 0), FLATSQL_IO_ERR_IO, "write on RO");
+      expectStatus(await io.truncate(ro, 0), FLATSQL_IO_ERR_IO, "truncate on RO");
+      await io.close(ro);
+      const wo = await io.open(`${dir}/m.bin`, FLATSQL_IO_WRITE);
+      expectHandle(wo, "write-only open");
+      expectStatus(await io.readInto(wo, new Uint8Array(2), 0), FLATSQL_IO_ERR_IO, "read on WO");
+      await io.close(wo);
+    },
+  },
+  {
+    name: "OPEN_DEFERRED: a failed open surfaces at open or at first use",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/deferred-missing.bin`, RW | FLATSQL_IO_OPEN_DEFERRED);
+      if (h < 0) {
+        expectStatus(h, FLATSQL_IO_ERR_NOENT, "sync host");
+      } else {
+        expectStatus(await io.readInto(h, new Uint8Array(1), 0), FLATSQL_IO_ERR_NOENT, "first use");
+        expectStatus(await io.close(h), 0, "close failed deferred");
+      }
+      const ok = await io.open(`${dir}/deferred.bin`, RWC | FLATSQL_IO_OPEN_DEFERRED);
+      expectHandle(ok, "deferred create");
+      expectStatus(await io.writeFrom(ok, encoder.encode("later"), 0), 5, "write after deferred");
+      expectStatus(await io.size(ok), 5, "size");
+      await io.close(ok);
+    },
+  },
+  {
+    name: "two handles on one path see each other's writes",
+    async run(io, dir) {
+      const a = await io.open(`${dir}/shared.bin`, RWC);
+      const b = await io.open(`${dir}/shared.bin`, RW);
+      expectHandle(a, "a");
+      expectHandle(b, "b");
+      await io.writeFrom(a, encoder.encode("from-a"), 0);
+      const buf = new Uint8Array(6);
+      expectStatus(await io.readInto(b, buf, 0), 6, "read via b");
+      expect(decoder.decode(buf) === "from-a", "b sees a");
+      await io.writeFrom(b, encoder.encode("B"), 0);
+      const one = new Uint8Array(1);
+      await io.readInto(a, one, 0);
+      expect(one[0] === 0x42, "a sees b");
+      await io.close(a);
+      await io.close(b);
+    },
+  },
+  {
+    name: "1 MiB round trip across chunk boundaries at an unaligned offset",
+    async run(io, dir) {
+      const h = await io.open(`${dir}/big.bin`, RWC);
+      expectHandle(h, "open");
+      const data = pattern(1024 * 1024 + 17, 0x9e3779b9);
+      expectStatus(await io.writeFrom(h, data, 4093), data.length, "write");
+      expectStatus(await io.size(h), 4093 + data.length, "size");
+      const back = new Uint8Array(data.length);
+      expectStatus(await io.readInto(h, back, 4093), data.length, "read");
+      expect(equalBytes(back, data), "bytes round trip");
+      await io.close(h);
+    },
+  },
+]);
+
+/**
+ * Run the conformance cases against `io`.
+ *
+ * @param {object} io provider (see the file header)
+ * @param {object} [options]
+ * @param {string} [options.prefix="conformance"] directory for the cases
+ * @param {string[]} [options.skip] case names to skip, each with a reason in
+ *   `options.skipReasons`
+ * @returns {Promise<{ passed: string[], failed: { name: string, error: string }[], skipped: string[] }>}
+ */
+export async function runFlatsqlIoConformance(io, options = {}) {
+  const prefix = options.prefix ?? "conformance";
+  const skip = new Set(options.skip ?? []);
+  const passed = [];
+  const failed = [];
+  const skipped = [];
+  let index = 0;
+  for (const testCase of FLATSQL_IO_CONFORMANCE_CASES) {
+    index += 1;
+    if (skip.has(testCase.name)) {
+      skipped.push(testCase.name);
+      continue;
+    }
+    const dir = `${prefix}/case-${String(index).padStart(2, "0")}`;
+    // Every case starts from its own existing directory.
+    const seed = await io.open(`${dir}/.keep`, RWC | FLATSQL_IO_CREATE_PARENTS);
+    if (seed >= 0) await io.close(seed);
+    try {
+      await testCase.run(io, dir);
+      passed.push(testCase.name);
+    } catch (error) {
+      failed.push({ name: testCase.name, error: String(error?.message ?? error) });
+    }
+  }
+  return { passed, failed, skipped };
+}
+
+/** Adapt the async channel client (bytes-returning read) to the script's shape. */
+export function conformanceAdapterForAsyncClient(client) {
+  return {
+    open: (path, flags) => client.open(path, flags),
+    async readInto(handle, view, offset) {
+      const result = await client.read(handle, view.length, offset);
+      if (typeof result === "number") return result;
+      view.set(result, 0);
+      return result.length;
+    },
+    writeFrom: (handle, view, offset) => client.write(handle, view, offset),
+    truncate: (handle, size) => client.truncate(handle, size),
+    sync: (handle) => client.sync(handle),
+    size: (handle) => client.size(handle),
+    close: (handle) => client.close(handle),
+  };
+}

package/src/host/flatsqlIoContract.js

@@ -0,0 +1,240 @@
+// The FlatSQL host I/O contract, as the SDK's JavaScript hosts implement it.
+//
+// FlatSQL's engine reaches files only through seven `env.flatsql_io_*` imports
+// (flatsql cpp/include/flatsql/flatsql_io.h). Every host satisfies the same
+// seven names with the same signatures: the SDN node's C host module, the Go
+// HostIO, the Node sync-fs provider (nodeSyncFsIo.js) and the browser I/O
+// workers (opfsIoWorker.mjs behind sabIoChannel.js). This file holds the
+// constants those hosts share, so the flag and status values are defined once.
+//
+// SIGNATURE LAW: i32 and f64 only. Offsets and sizes cross as f64.
+// ERROR LAW: errors are negative return values, never throws. A throw out of an
+// import is a trap, and a trap poisons the calling instance.
+//
+// The partition store (docs/architecture/flatsql-partition-store.md §5.4, A12,
+// A38) adds three open flags and one status. They are flags, not imports, so the
+// import set stays at seven.
+
+/** Open flags. Values must stay identical to flatsql_io.h. */
+export const FLATSQL_IO_READ = 0x0001;
+export const FLATSQL_IO_WRITE = 0x0002;
+export const FLATSQL_IO_CREATE = 0x0004;
+export const FLATSQL_IO_EXCL = 0x0008;
+export const FLATSQL_IO_TRUNC = 0x0010;
+/** Advisory: the host drops the file when its last handle closes. */
+export const FLATSQL_IO_DELETE_ON_CLOSE = 0x0020;
+/** xAccess: returns 0 when the path exists, NOENT otherwise. No handle. */
+export const FLATSQL_IO_PROBE = 0x0040;
+/** xDelete: removes the path. No handle. */
+export const FLATSQL_IO_UNLINK = 0x0080;
+/**
+ * mkdir -p the parent directories. Each created directory's parent is synced,
+ * and the parent directory is synced when the file itself is newly created.
+ * (OPFS directory durability is best effort; see §7 and 22.3a-4.)
+ */
+export const FLATSQL_IO_CREATE_PARENTS = 0x0100;
+/** Unlink, but return BUSY while any handle on the path is open. */
+export const FLATSQL_IO_UNLINK_IF_UNUSED = 0x0200;
+/**
+ * Return a handle before the open completes (A38). The first read or write on
+ * the handle blocks only if the open is still pending, and fails with the
+ * open's status if it failed. Hosts whose opens are synchronous (WasmEdge,
+ * Node) treat the flag as a plain open.
+ */
+export const FLATSQL_IO_OPEN_DEFERRED = 0x0400;
+
+/** Status codes. Every one is negative. */
+export const FLATSQL_IO_OK = 0;
+export const FLATSQL_IO_ERR_GENERIC = -1;
+export const FLATSQL_IO_ERR_NOENT = -2;
+export const FLATSQL_IO_ERR_ACCESS = -3;
+export const FLATSQL_IO_ERR_IO = -4;
+export const FLATSQL_IO_ERR_NOSPACE = -5;
+export const FLATSQL_IO_ERR_BADHANDLE = -6;
+/** A12: the path is in use (UNLINK_IF_UNUSED), or its lock is held elsewhere. */
+export const FLATSQL_IO_ERR_BUSY = -7;
+
+export const FLATSQL_IO_FLAGS = Object.freeze({
+  READ: FLATSQL_IO_READ,
+  WRITE: FLATSQL_IO_WRITE,
+  CREATE: FLATSQL_IO_CREATE,
+  EXCL: FLATSQL_IO_EXCL,
+  TRUNC: FLATSQL_IO_TRUNC,
+  DELETE_ON_CLOSE: FLATSQL_IO_DELETE_ON_CLOSE,
+  PROBE: FLATSQL_IO_PROBE,
+  UNLINK: FLATSQL_IO_UNLINK,
+  CREATE_PARENTS: FLATSQL_IO_CREATE_PARENTS,
+  UNLINK_IF_UNUSED: FLATSQL_IO_UNLINK_IF_UNUSED,
+  OPEN_DEFERRED: FLATSQL_IO_OPEN_DEFERRED,
+});
+
+export const FLATSQL_IO_STATUS = Object.freeze({
+  OK: FLATSQL_IO_OK,
+  GENERIC: FLATSQL_IO_ERR_GENERIC,
+  NOENT: FLATSQL_IO_ERR_NOENT,
+  ACCESS: FLATSQL_IO_ERR_ACCESS,
+  IO: FLATSQL_IO_ERR_IO,
+  NOSPACE: FLATSQL_IO_ERR_NOSPACE,
+  BADHANDLE: FLATSQL_IO_ERR_BADHANDLE,
+  BUSY: FLATSQL_IO_ERR_BUSY,
+});
+
+/** The seven import names, module "env". */
+export const FLATSQL_IO_IMPORT_MODULE = "env";
+export const FLATSQL_IO_IMPORT_NAMES = Object.freeze([
+  "flatsql_io_open",
+  "flatsql_io_read",
+  "flatsql_io_write",
+  "flatsql_io_truncate",
+  "flatsql_io_sync",
+  "flatsql_io_size",
+  "flatsql_io_close",
+]);
+
+/** Longest path any SDK host accepts, in UTF-8 bytes (the Go host's limit). */
+export const FLATSQL_IO_MAX_PATH_BYTES = 4096;
+
+/**
+ * Map a thrown host error to a status. Covers DOMExceptions from OPFS
+ * (22.3a-6: NotFound -> NOENT, NoModificationAllowed -> BUSY, QuotaExceeded ->
+ * NOSPACE) and Node system errors.
+ *
+ * WebKit refuses a second sync access handle with InvalidStateError rather
+ * than NoModificationAllowedError (measured, WebKit 26.6), so an
+ * InvalidStateError raised while OPENING maps to BUSY; pass
+ * `{ during: "open" }` for that case.
+ */
+export function flatsqlIoStatusForError(error, { during } = {}) {
+  if (!error) {
+    return FLATSQL_IO_ERR_GENERIC;
+  }
+  const code = typeof error.code === "string" ? error.code : null;
+  if (code) {
+    switch (code) {
+      case "ENOENT":
+      case "ENOTDIR":
+        return FLATSQL_IO_ERR_NOENT;
+      case "EACCES":
+      case "EPERM":
+      case "EROFS":
+        return FLATSQL_IO_ERR_ACCESS;
+      case "ENOSPC":
+      case "EDQUOT":
+        return FLATSQL_IO_ERR_NOSPACE;
+      case "EBADF":
+        return FLATSQL_IO_ERR_IO;
+      case "EEXIST":
+        // The Go host maps os.ErrExist to GENERIC; every SDK host matches it.
+        return FLATSQL_IO_ERR_GENERIC;
+      case "EBUSY":
+      case "ETXTBSY":
+        return FLATSQL_IO_ERR_BUSY;
+      case "ENAMETOOLONG":
+      case "EINVAL":
+        return FLATSQL_IO_ERR_GENERIC;
+      default:
+        return FLATSQL_IO_ERR_IO;
+    }
+  }
+  switch (error.name) {
+    case "NotFoundError":
+      return FLATSQL_IO_ERR_NOENT;
+    case "NoModificationAllowedError":
+      return FLATSQL_IO_ERR_BUSY;
+    case "InvalidStateError":
+      return during === "open" ? FLATSQL_IO_ERR_BUSY : FLATSQL_IO_ERR_BADHANDLE;
+    case "QuotaExceededError":
+      return FLATSQL_IO_ERR_NOSPACE;
+    case "TypeMismatchError":
+    case "SecurityError":
+    case "NotAllowedError":
+      return FLATSQL_IO_ERR_ACCESS;
+    case "InvalidModificationError":
+      return FLATSQL_IO_ERR_BUSY;
+    case "TypeError":
+    case "RangeError":
+      return FLATSQL_IO_ERR_GENERIC;
+    default:
+      return FLATSQL_IO_ERR_IO;
+  }
+}
+
+/** An Error carrying a flatsql_io status, thrown inside hosts and caught at the edge. */
+export class FlatsqlIoStatusError extends Error {
+  constructor(status, message) {
+    super(message ?? `flatsql_io status ${status}`);
+    this.name = "FlatsqlIoStatusError";
+    this.status = status;
+  }
+}
+
+/** Status for any error thrown inside a host, honouring FlatsqlIoStatusError. */
+export function flatsqlIoStatusOf(error, options) {
+  if (error && typeof error.status === "number" && error.status < 0) {
+    return error.status;
+  }
+  return flatsqlIoStatusForError(error, options);
+}
+
+/**
+ * Split a guest path into components below a host root. Paths are opaque
+ * host-namespace strings to the engine; confinement is the host's job and it
+ * fails closed: "", ".", ".." and NUL are refused with ACCESS (".." would
+ * escape) or GENERIC (malformed). A leading "/" is ignored, so "/a/b" and "a/b"
+ * name the same file below the root. Returns an array of components, or a
+ * negative status.
+ */
+export function splitFlatsqlIoPath(path) {
+  if (typeof path !== "string" || path.length === 0) {
+    return FLATSQL_IO_ERR_GENERIC;
+  }
+  if (path.includes("\0")) {
+    return FLATSQL_IO_ERR_GENERIC;
+  }
+  const components = [];
+  for (const part of path.split("/")) {
+    if (part === "" || part === ".") {
+      continue;
+    }
+    if (part === "..") {
+      return FLATSQL_IO_ERR_ACCESS;
+    }
+    components.push(part);
+  }
+  if (components.length === 0) {
+    return FLATSQL_IO_ERR_GENERIC;
+  }
+  return components;
+}
+
+/** Decode path bytes that may live in a SharedArrayBuffer (copied first). */
+const PATH_DECODER =
+  typeof TextDecoder === "function" ? new TextDecoder("utf-8", { fatal: true }) : null;
+
+export function decodeFlatsqlIoPath(bytes) {
+  if (!PATH_DECODER) {
+    return FLATSQL_IO_ERR_GENERIC;
+  }
+  if (bytes.length === 0 || bytes.length > FLATSQL_IO_MAX_PATH_BYTES) {
+    return FLATSQL_IO_ERR_GENERIC;
+  }
+  // TextDecoder rejects views over a SharedArrayBuffer in some engines, and a
+  // shared view can change under the decoder. Decode a private copy.
+  const copy =
+    bytes.buffer instanceof ArrayBuffer ? bytes : new Uint8Array(bytes);
+  try {
+    return PATH_DECODER.decode(copy);
+  } catch {
+    return FLATSQL_IO_ERR_GENERIC;
+  }
+}
+
+/** Word-folded-free FNV-1a 32 over path bytes; used to shard paths across workers. */
+export function hashFlatsqlIoPath(bytes) {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < bytes.length; i += 1) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}