Refactor package build lifecycle and improve resource management

.changeset/structural-map-uint8array.md

@@ -0,0 +1,7 @@
+---
+"@evolu/common": minor
+---
+
+Added `StructuralMap`, a `Map`-like collection for registries and coordination tables where callers have immutable JSON-like keys or `Uint8Array` keys and do not want to maintain a separate string id.
+
+`StructuralMap` works by deriving a canonical structural id for each key and storing entries in a native `Map` keyed by that id. Repeated lookups of the same object or array instance reuse cached ids through a `WeakMap`.

.github/copilot-instructions.md

@@ -241,7 +241,9 @@ const result = await run(fetchUser("123"));
 
 ## Test-driven development
 
-- Write a test before implementing a new feature or fixing a bug
+- Tests are required for new features and bug fixes
+- Prefer writing or updating tests before implementation when behavior or API shape is still being clarified
+- When the implementation is straightforward from established patterns, implementation may come first
 - Test files are in `packages/*/test/*.test.ts`
 - Use `testNames` parameter to run specific tests — uses **substring matching**, so unique names avoid running unrelated tests
 - Run only changed/affected tests, not entire describe blocks

.github/workflows/ci.yaml

@@ -128,14 +128,14 @@ jobs:
       - name: Relay smoke tests (Bun runtime)
         if: matrix.runtime == 'bun'
         run: >
-          bunx vitest run --project unit
+          bunx vitest run --project "@evolu/common (nodejs)"
           packages/common/test/WebSocket.test.ts
           packages/common/test/local-first/Relay.test.ts
 
       - name: Relay smoke tests (Node runtime)
         if: matrix.runtime == 'node'
         run: >
-          node ./node_modules/vitest/vitest.mjs run --project unit
+          node ./node_modules/vitest/vitest.mjs run --project "@evolu/common (nodejs)"
           packages/common/test/WebSocket.test.ts
           packages/common/test/local-first/Relay.test.ts
 

.github/workflows/ws-browser-nightly.yaml

@@ -42,7 +42,7 @@ jobs:
       - name: Run browser WebSocket tests
         run: |
           set -o pipefail
-          bunx vitest run --project browser packages/common/test/WebSocket.test.ts --reporter=verbose 2>&1 | tee ws-browser-nightly.log
+          bunx vitest run --project "@evolu/common" packages/common/test/WebSocket.test.ts --reporter=verbose 2>&1 | tee ws-browser-nightly.log
 
       - name: Upload browser WebSocket logs
         if: always()

.gitignore

@@ -17,6 +17,7 @@ storybook-static
 out
 test-identicons
 coverage
+.vitest-attachments
 tmp
 __screenshots__
 *.tsBuildInfo

apps/relay/package.json

@@ -19,7 +19,7 @@
   },
   "devDependencies": {
     "@evolu/tsconfig": "workspace:*",
-    "@types/node": "^25.3.3",
+    "@types/node": "^25.5.0",
     "typescript": "^5.9.3"
   },
   "engines": {

apps/relay/src/index.ts

@@ -1,7 +1,6 @@
 import { mkdirSync } from "node:fs";
 import { createConsole, createConsoleFormatter } from "@evolu/common";
-import { createRelayDeps, createRunner, startRelay } from "@evolu/nodejs";
-import { startBunRelay } from "./startBunRelay.js";
+import { createRelayDeps, createRun, startRelay } from "@evolu/nodejs";
 
 // Ensure the database is created in a predictable location for Docker.
 mkdirSync("data", { recursive: true });
@@ -16,24 +15,23 @@ const console = createConsole({
 
 const deps = { ...createRelayDeps(), console };
 
-await using run = createRunner(deps);
-await using stack = run.stack();
+await using run = createRun(deps);
+await using stack = new AsyncDisposableStack();
 
-const isBunRuntime = (globalThis as { readonly Bun?: unknown }).Bun != null;
-const startRelayTask = isBunRuntime ? startBunRelay : startRelay;
+stack.use(
+  await run.orThrow(
+    startRelay({
+      port: 4000,
 
-await stack.use(
-  startRelayTask({
-    port: 4000,
+      // Note: Relay requires URL in format ws://host:port/<ownerId>
+      // isOwnerAllowed: (_ownerId) => true,
 
-    // Note: Relay requires URL in format ws://host:port/<ownerId>
-    // isOwnerAllowed: (_ownerId) => true,
-
-    isOwnerWithinQuota: (_ownerId, requiredBytes) => {
-      const maxBytes = 1024 * 1024; // 1MB
-      return requiredBytes <= maxBytes;
-    },
-  }),
+      isOwnerWithinQuota: (_ownerId, requiredBytes) => {
+        const maxBytes = 1024 * 1024; // 1MB
+        return requiredBytes <= maxBytes;
+      },
+    }),
+  ),
 );
 
 await run.deps.shutdown;

apps/relay/src/startBunRelay.ts

@@ -1,8 +1,6 @@
 import {
   type CreateSqliteDriverDep,
-  callback,
   createSqlite,
-  getOrThrow,
   isPromiseLike,
   type OwnerId,
   ok,
@@ -95,11 +93,11 @@ export const startBunRelay =
       throw new Error("startBunRelay requires Bun runtime.");
     }
 
-    await using stack = _run.stack();
+    await using stack = new AsyncDisposableStack();
     const console = _run.deps.console.child("relay");
 
     const relayName = name ?? SimpleName.orThrow("evolu-relay");
-    const sqlite = getOrThrow(await stack.use(createSqlite(relayName)));
+    const sqlite = stack.use(await _run.orThrow(createSqlite(relayName)));
     const deps = { ..._run.deps, sqlite };
 
     createBaseSqliteStorageTables(deps);
@@ -255,17 +253,13 @@ export const startBunRelay =
 
     stack.defer(() => {
       console.info("Shutdown complete");
-      return ok();
     });
 
-    stack.defer(
-      callback(({ ok }) => {
-        console.info("Shutting down...");
-        server.stop(true);
-        console.info("Bun server stopped");
-        ok();
-      }),
-    );
+    stack.defer(() => {
+      console.info("Shutting down...");
+      server.stop(true);
+      console.info("Bun server stopped");
+    });
 
     console.info(`Started on port ${port} (Bun native runtime)`);
 

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.6/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",