@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/test/compile.ts

@@ -0,0 +1,501 @@
+// Single-app realm.ts → HomeApp orchestrator for tests.
+//
+// Mirrors the slice of Home's eval pipeline that doesn't depend on a
+// multi-app world: extractSchema → resolvePermissions → merge config +
+// perms → execute in sandbox → resolveRefs → checkAppGrants. The world
+// is whatever the fixture supplies in `peers` (empty by default); a
+// `peers.*` permission without a grant resolves to `[]`, same as Home.
+// remote.* is unfetched, so a realm.ts consuming one surfaces a
+// validation error.
+//
+// `compile` never throws: a pipeline error becomes
+// `{error: true, issues: [...]}`. An eval crash surfaces as an `eval`
+// issue, an elevated *use* without a backing grant as a `permission`
+// issue from `checkAppGrants`. Declared-but-unused ungranted
+// permissions stay silent, same as production.
+
+import { execute, executeDeferred, executeInfo, extractSchema, nestByPaths } from "../sandbox.ts";
+import { buildAllowMap, resolveRefs, type ResolutionContext } from "../generator/resolve-refs.ts";
+import { firstPublicDomain, serviceUrl } from "../service-url.ts";
+import { normalizeInfo, type ResolvedInfoEntry } from "../info.ts";
+import { replaceSecrets } from "../compile.ts";
+import { sha256Hex } from "../generator/hash.ts";
+import { deepMergeConfig } from "../deep-merge.ts";
+import { RealmCompileError, type CompileIssue, formatIssue } from "../errors.ts";
+import {
+  checkAppGrants,
+  grantsSchema,
+  sanitizeGrants,
+  siloMountKey,
+  type Violation,
+} from "../security.ts";
+import { type SiloGrants, type SiloResolved } from "../schema/host.ts";
+import { isHomeGrant, isHostGrant, resolveValue } from "../grants.ts";
+import type { ResolveContext } from "../resolve-context.ts";
+import { peerHooks, resolvePeerValue, type WorldState } from "../peer-world.ts";
+import type { AllowedProvider } from "../peer-registry.ts";
+import type { PeerPermissionKind } from "../permissions.ts";
+import type { Grants } from "../grants.ts";
+import type { Network } from "../identifiers.ts";
+import { homeProxyMount } from "../worker-protocol/home-proxy-paths.ts";
+import { spawnMounts } from "../worker-protocol/spawn-paths.ts";
+import type { WorkerHostPath } from "../worker-protocol/logs-socket-path.ts";
+import type { WorkerMount } from "../worker-protocol/worker-mount.ts";
+import type { HomeApp } from "../resolve.ts";
+import type { SerializablePermission } from "../sandbox.ts";
+import type { CompileFixture, CompileResult } from "./types.ts";
+
+interface CompileInputs<App> {
+  bundledCode: string;
+  appName: string;
+  fixture: CompileFixture<App>;
+}
+
+export async function compile<App>(inputs: CompileInputs<App>): Promise<CompileResult> {
+  const { bundledCode, appName, fixture } = inputs;
+  const appId = fixture.appId ?? appName;
+  const issues: CompileIssue[] = [];
+  const grantViolations: Violation[] = [];
+
+  let permissionsFlat: Record<string, SerializablePermission>;
+  let secretPaths: string[];
+  try {
+    const extracted = await extractSchema(bundledCode);
+    permissionsFlat = extracted.permissionsFlat;
+    secretPaths = extracted.secretPaths;
+  } catch (err) {
+    return errorResult([...issues, ...issuesFromError(err)], grantViolations);
+  }
+
+  const { sanitized: config, secrets } = replaceSecrets(
+    fixture.config as Record<string, unknown>,
+    secretPaths,
+  );
+
+  let grants: Grants;
+  try {
+    const parsed = grantsSchema.parse((fixture.grants ?? {}) as unknown);
+    grants = sanitizeGrants(permissionsFlat, parsed).sanitized;
+  } catch (err) {
+    return errorResult([...issues, ...issuesFromError(err)], grantViolations);
+  }
+
+  const world: WorldState = fixture.peers ?? [];
+  let resolved: ResolvedPerms;
+  try {
+    resolved = await resolvePermissions(
+      permissionsFlat,
+      grants,
+      world,
+      appId,
+      fixture.management,
+      fixture.homeApi,
+      fixture.spawn,
+      fixture.silo,
+    );
+  } catch (err) {
+    // An unmet silo require-map (or a fixture-usage slip) lands as a
+    // CompileResult issue rather than escaping compile(), mirroring how Home
+    // turns the same throw into a drop.
+    return errorResult([...issues, ...issuesFromError(err)], grantViolations);
+  }
+  const nestedPermissions = nestByPaths(resolved.values);
+  const data = deepMergeConfig(config, nestedPermissions);
+
+  const preview = fixture.preview ?? null;
+  let state: HomeApp;
+  try {
+    // No cache key: a fixture run compiles one source against many configs, so
+    // every call would miss `execute`'s per-app slot anyway.
+    state = await execute(bundledCode, data, appId, null, preview);
+  } catch (err) {
+    return errorResult([...issues, ...issuesFromError(err)], grantViolations);
+  }
+
+  let walked: HomeApp;
+  let infoEntries: ResolvedInfoEntry[] = [];
+  try {
+    const seed = fixture.seed ?? "test";
+    const derivationSeed = await crypto.subtle.importKey(
+      "raw",
+      new TextEncoder().encode(seed),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"],
+    );
+    const resolveCtx: ResolutionContext = {
+      consumerAppId: appId,
+      derivationSeed,
+      secrets,
+      allowedProviders: buildAllowMap(resolved.allowedProviders),
+      derivedCache: new Map(),
+      runDeferred: (items) => executeDeferred(bundledCode, data, appId, items, preview),
+    };
+    const services: Record<string, unknown> = { ...state.services };
+    // Pass `ui` through the walker too — loader.headers may carry ref
+    // markers the dev server and boot tests need resolved. Omit when
+    // absent so apps without a `ui:` block don't acquire a spurious
+    // `ui: undefined` key on the resolved state.
+    const walkInput: Record<string, unknown> = { services };
+    if (state.ui !== undefined) walkInput.ui = state.ui;
+    if (state.egress) walkInput.egress = state.egress;
+    // trustedHeaders is plain sampled data (no ref markers) but result.state
+    // consumers (and the Caddy peer extract) read it, so carry it through.
+    if (state.trustedHeaders !== undefined) walkInput.trustedHeaders = state.trustedHeaders;
+    walked = (await resolveRefs(walkInput as unknown as HomeApp, resolveCtx)) as HomeApp;
+    // Defense-in-depth: a marker landing in a field the walker doesn't
+    // recognize passes through unresolved, which in production renders
+    // `{__realmRef: ...}` into compose YAML. Throw so the test fails
+    // loud. Mirrors `build-wire.ts`.
+    assertNoRefMarkers(walked, ["state"]);
+
+    // Resolve `info` on the same separate path Home's summary page uses.
+    infoEntries = await resolveCompileInfo(
+      bundledCode,
+      walked,
+      appId,
+      fixture.baseDomain ?? null,
+      fixture.slug ?? null,
+      resolveCtx,
+    );
+  } catch (err) {
+    return errorResult([...issues, ...issuesFromError(err)], grantViolations);
+  }
+
+  const violations = checkAppGrants(walked, grants, permissionsFlat, {
+    allowedNetworks: resolved.networks,
+    allowedAbsoluteHostPaths: resolved.absoluteHostPaths,
+    readOnlyHostPaths: resolved.readOnlyHostPaths,
+    allowedSiloMounts: resolved.siloMounts,
+  });
+  for (const v of violations) {
+    grantViolations.push(v);
+    issues.push(violationToIssue(v));
+  }
+
+  if (issues.length > 0) return errorResult(issues, grantViolations);
+  return { error: false, app: walked, info: infoEntries };
+}
+
+// Build the `services` URL map + run `app.info`, resolving its refs with the
+// already-built walk context. Own try/catch so a broken `info` never fails an
+// otherwise-good compile (matches Home's leniency).
+async function resolveCompileInfo(
+  bundledCode: string,
+  state: HomeApp,
+  appId: string,
+  baseDomain: string | null,
+  slug: string | null,
+  ctx: ResolutionContext,
+): Promise<ResolvedInfoEntry[]> {
+  try {
+    const services: Record<string, string | null> = {};
+    for (const [name, svc] of Object.entries(state.services)) {
+      services[name] = serviceUrl({
+        appId,
+        serviceId: name,
+        slug,
+        baseDomain,
+        publicDomain: firstPublicDomain(svc.router?.publicDomain),
+        hasRouter: svc.router != null,
+      });
+    }
+    const raw = await executeInfo(bundledCode, services);
+    if (raw == null) return [];
+    const resolved = (await resolveRefs(raw, ctx)) as Record<string, unknown>;
+    return normalizeInfo(resolved);
+  } catch {
+    return [];
+  }
+}
+
+function errorResult(issues: CompileIssue[], violations: Violation[]): CompileResult {
+  return {
+    error: true,
+    message: issues.length === 1 ? formatIssue(issues[0]!) : `${issues.length} compile errors`,
+    issues,
+    violations,
+  };
+}
+
+function issuesFromError(err: unknown): CompileIssue[] {
+  if (err instanceof RealmCompileError) return [...err.issues];
+  return [{ kind: "eval", message: err instanceof Error ? err.message : String(err) }];
+}
+
+function violationToIssue(v: Violation): CompileIssue {
+  if (v.kind === "eval") return { kind: "eval", message: v.message };
+  if (v.kind === "worker-capability") {
+    return {
+      kind: "permission",
+      missing: `${v.missing.join(", ")} (worker ${v.workerId} can't satisfy)`,
+    };
+  }
+  if (v.kind === "app-kind") {
+    return { kind: "validation", path: ["kind"], message: v.description };
+  }
+  if (v.kind === "routing") {
+    return { kind: "validation", path: ["router", "publicDomain"], message: v.description };
+  }
+  const where = v.serviceName
+    ? ` (used by service "${v.serviceName}" without a matching grant)`
+    : " (no matching grant)";
+  return {
+    kind: "permission",
+    missing: `${v.permissionKind}${where}`,
+  };
+}
+
+function assertNoRefMarkers(value: unknown, path: string[]): void {
+  if (value == null || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      assertNoRefMarkers(value[i], [...path, String(i)]);
+    }
+    return;
+  }
+  if ("__realmRef" in (value as Record<string, unknown>)) {
+    throw new RealmCompileError({
+      kind: "eval",
+      message: `unresolved ref marker leaked into resolved state at ${path.join(".")}`,
+    });
+  }
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    assertNoRefMarkers(v, [...path, k]);
+  }
+}
+
+interface ResolvedPerms {
+  values: Record<string, unknown>;
+  networks: Set<Network>;
+  absoluteHostPaths: Set<string>;
+  readOnlyHostPaths: Map<string, string>;
+  siloMounts: Set<string>;
+  allowedProviders: AllowedProvider[];
+}
+
+async function resolvePermissions(
+  permsFlat: Record<string, SerializablePermission>,
+  grants: Grants,
+  world: WorldState,
+  appId: string,
+  managementOverride: CompileFixture<unknown>["management"],
+  homeApiOverride: CompileFixture<unknown>["homeApi"],
+  spawnOverride: CompileFixture<unknown>["spawn"],
+  siloOverride: CompileFixture<unknown>["silo"],
+): Promise<ResolvedPerms> {
+  const values: Record<string, unknown> = {};
+  const networks = new Set<Network>();
+  const absoluteHostPaths = new Set<string>();
+  const readOnlyHostPaths = new Map<string, string>();
+  const siloMounts = new Set<string>();
+  const allowedProviders: AllowedProvider[] = [];
+
+  // Mirrors graph.ts collectAllowed: exempt the mount from the absolute-mount
+  // gate, and remember which paths the grant only covers read-only (against the
+  // kind that granted them, so the violation names the right permission).
+  //
+  // Writable wins, same as graph.ts: two permissions can resolve to the same
+  // path with different modes, and the map is keyed by path alone, so the
+  // second pass below clears the read-only mark a writable mount also earned.
+  const writableHostPaths = new Set<string>();
+  const allowMount = (mount: { hostPath: string; readOnly: boolean } | undefined, kind: string) => {
+    if (!mount?.hostPath) return;
+    absoluteHostPaths.add(mount.hostPath);
+    if (mount.readOnly) readOnlyHostPaths.set(mount.hostPath, kind);
+    else writableHostPaths.add(mount.hostPath);
+  };
+
+  // The eval-time world, from fixture data instead of Home's database. Home
+  // builds the same shape in graph.ts, so the resolvers can't tell the
+  // difference.
+  const siloFixtures = siloOverride ?? {};
+  // Fixture-usage checks, per granted declaration. Home reads these fields off a
+  // Silo row that always has them, so a missing one is a test-authoring problem
+  // rather than a resolution failure an operator would ever see - worth its own
+  // message instead of the resolver's.
+  //
+  // Only granted paths are checked: an optional silo compiled WITHOUT its grant
+  // never reaches the resolver, so it asks nothing of the fixture either.
+  for (const [path, perm] of Object.entries(permsFlat)) {
+    if (perm.kind !== "host.silo") continue;
+    const grant = grants[path];
+    if (grant?.kind !== "host.silo" || typeof grant.data !== "string") continue;
+    const siloId = grant.data;
+    const fixture = siloFixtures[siloId];
+    if (fixture === undefined) {
+      throw new Error(
+        `${path}: granted Silo "${siloId}" has no fixture — add \`silo: { ${siloId}: {…} }\``,
+      );
+    }
+    if ((perm.data as SiloGrants).volume === undefined) continue;
+    if (fixture.hostPath === undefined || fixture.gid === undefined) {
+      throw new Error(
+        `${path}: the ask includes \`volume\` — set \`silo: { ${siloId}: { hostPath, gid } }\``,
+      );
+    }
+  }
+  const ctx: ResolveContext = {
+    appId,
+    // No worker identity in a compile-tier test, so `internalId` stays absent
+    // and silo's placement check doesn't fire (there is no wrong worker to be
+    // on).
+    worker: { id: managementOverride?.workerId ?? "" },
+    home: {
+      baseDomain: managementOverride?.baseDomain ?? "",
+      homeSlug: managementOverride?.homeSlug ?? "",
+      // The fixture supplies the whole acmeDns block including `username`,
+      // which the real resolver derives from baseDomain - so a fixture that
+      // sets one keeps its own value by overriding after resolution below.
+      acmeDns: managementOverride?.acmeDns ?? null,
+    },
+    // One record per fixture entry, keyed by the id the grant carries. Two
+    // entries means two Silos with their own directories, exactly as Home would
+    // read two rows.
+    silos: Object.entries(siloFixtures).map(([id, f]) => ({
+      id,
+      // Home names the Silo in require-map failures; a fixture has no name, so
+      // the id stands in.
+      name: id,
+      workerId: "",
+      workerSlug: "",
+      hostPath: f.hostPath ?? "",
+      containerPath: f.containerPath ?? "/silo",
+      gid: f.gid ?? 0,
+    })),
+    // Per Silo, so a require-map against one never sees another's publications.
+    siloDirectory: (siloId) =>
+      new Map(
+        Object.entries(siloFixtures[siloId]?.services ?? {}).map(([name, port]) => [
+          name,
+          { port, appId: "fixture-peer" },
+        ]),
+      ),
+    // Production *shape* (64-char hex) without REALM_SECRET; stable per Silo id
+    // so two members of one fixture Silo read the same key.
+    siloApiKeys: new Map(
+      await Promise.all(
+        Object.entries(siloFixtures).map(
+          async ([id, f]) => [id, f.apiKey ?? (await sha256Hex(`test-silo-apikey-${id}`))] as const,
+        ),
+      ),
+    ),
+  };
+
+  for (const [path, perm] of Object.entries(permsFlat)) {
+    const kind = perm.kind;
+
+    if (kind.startsWith("peers.")) {
+      // Mirror Home: ungranted peer permissions resolve to []; granted
+      // ones run through the registry against the supplied world. Each
+      // resolved entry also contributes networks / absolute host paths /
+      // shared providers to the security check.
+      const g = grants[path];
+      const granted = g != null && g.kind === kind;
+      const value = granted
+        ? (resolvePeerValue(kind as PeerPermissionKind, perm.data, world) as unknown[])
+        : [];
+      values[path] = value;
+      if (granted && Array.isArray(value)) {
+        const hooks = peerHooks(kind);
+        if (hooks) {
+          for (const entry of value) {
+            if (!entry || typeof entry !== "object") continue;
+            const net = hooks.extractNetworks?.(entry);
+            if (net) networks.add(net);
+            const vol = hooks.extractPeerVolumes?.(entry);
+            if (vol) absoluteHostPaths.add(vol);
+            const provider = hooks.extractAllowedProvider?.(entry);
+            if (provider) allowedProviders.push(provider);
+          }
+        }
+      }
+      continue;
+    }
+
+    // host.* and home.* run through the SAME registry dispatch Home uses
+    // (resolve-permissions.ts) against a context built from the fixture, so an
+    // app's own tests can't green-light something Home would reject.
+    //
+    // remote.* + unknown: no value here. A realm.ts that reads one will trip a
+    // downstream validation error.
+    const grant = grants[path];
+    if (!grant || grant.kind !== kind || !(isHostGrant(grant) || isHomeGrant(grant))) {
+      values[path] = undefined;
+      continue;
+    }
+    values[path] = resolveValue(grant, { declared: perm.data, path, ctx });
+  }
+
+  // The collectAllowed half of the sweep, mirroring graph.ts: fold resolved
+  // networks in and exempt resolved mounts from the absolute-mount gate. Reads
+  // the resolved value, not grant.data — these grants carry presence-only
+  // (`true`) data while the real value came out of the resolver above.
+  for (const [path, perm] of Object.entries(permsFlat)) {
+    const value = values[path];
+    if (perm.kind === "host.management" && value && typeof value === "object") {
+      const mgmt = value as {
+        network: Network;
+        baseDomain: string;
+        homeSlug: string;
+        workerId: string;
+        acmeDns: {
+          serverUrl: string;
+          username: string;
+          apiKey: string;
+          ca: string;
+          caRootPem: string;
+        } | null;
+      };
+      networks.add(mgmt.network);
+      // `acmeDns` is the one field not taken straight off the context: the
+      // fixture's whole block, `username` included, wins over the derived one.
+      if (managementOverride?.acmeDns !== undefined) {
+        values[path] = { ...mgmt, acmeDns: managementOverride.acmeDns };
+      }
+    } else if (perm.kind === "host.logs" || perm.kind === "host.stats") {
+      allowMount(value as WorkerMount | undefined, perm.kind);
+    } else if (perm.kind === "host.silo" && value && typeof value === "object") {
+      // Already resolved above through the real resolver. What's left is the
+      // collectAllowed half: the shared directory is exempted from the
+      // absolute-mount gate and recorded as a (hostPath, gid) pair, and the
+      // silo network folds into allowedNetworks.
+      const resolvedSilo = value as SiloResolved;
+      if (resolvedSilo.network) networks.add(resolvedSilo.network);
+      if (resolvedSilo.volume) {
+        allowMount(resolvedSilo.volume, perm.kind);
+        siloMounts.add(siloMountKey(resolvedSilo.volume.hostPath, resolvedSilo.volume.gid));
+      }
+    } else if (perm.kind === "host.spawn" && value && typeof value === "object") {
+      // host.spawn resolves to `{socket, scratch, artifacts}` mounts, built
+      // per-app by its resolver; the fixture overrides only the host paths. All
+      // three are exempted from the absolute-mount gate, so mounting needs only
+      // the grant (mirrors graph.ts collectAllowed). No network exemption: the
+      // box joins the DMZ broker-side, and no app service may sit on it.
+      const spawn = spawnMounts(appId);
+      const socket = withHostPath(spawn.socket, spawnOverride?.socket);
+      const scratch = withHostPath(spawn.scratch, spawnOverride?.scratch);
+      const artifacts = withHostPath(spawn.artifacts, spawnOverride?.artifacts);
+      values[path] = { socket, scratch, artifacts };
+      allowMount(socket, perm.kind);
+      allowMount(scratch, perm.kind);
+      allowMount(artifacts, perm.kind);
+    } else if (perm.kind === "home.apiAccess" && value && typeof value === "object") {
+      // home.apiAccess resolves to `{socket}`, the per-app socket mount its
+      // resolver builds; the fixture overrides only its host path. It is exempt
+      // from the absolute-mount gate (mirrors graph.ts collectAllowed).
+      const socket = withHostPath(homeProxyMount(appId), homeApiOverride?.socket);
+      values[path] = { socket };
+      allowMount(socket, perm.kind);
+    }
+  }
+
+  for (const p of writableHostPaths) readOnlyHostPaths.delete(p);
+
+  return { values, networks, absoluteHostPaths, readOnlyHostPaths, siloMounts, allowedProviders };
+}
+
+/** Swap a resolved mount's host path for the fixture's, keeping the rest. */
+function withHostPath(mount: WorkerMount, hostPath: string | undefined): WorkerMount {
+  return hostPath === undefined ? mount : { ...mount, hostPath: hostPath as WorkerHostPath };
+}

package/src/test/describe.ts

@@ -0,0 +1,117 @@
+// Realm.describe: the test-harness entry point. Wraps Deno.test so each
+// test in the block sees a typed `t` whose `compile` and `boot` are
+// constrained by the imported app.
+//
+// Bundling is shared across tests and lazy: the first `t.compile` (or
+// `t.boot`) call drives the bundle, subsequent calls await the same
+// Promise, and a run with every test filtered out bundles nothing.
+//
+// `test.e2e(...)` is a sibling of `test(...)` reserved for tier-2 e2e
+// tests. It registers via `Deno.test.ignore` unless `REALM_TEST_E2E=1`
+// is set, so the default `realm-sdk test` loop stays compile-only.
+// `e2e` is the test tier; `t.boot(...)` inside the body is the action
+// that renders compose, runs `docker compose up`, and connects Playwright.
+
+import { basename, dirname, fromFileUrl } from "@std/path";
+import { bundle } from "../bundle.ts";
+import type { AppDefinition } from "../create-app.ts";
+import { mergeSurfaces } from "../surfaces.ts";
+import type { ConfigSchema } from "../types.ts";
+import { compile as runCompile } from "./compile.ts";
+import { boot as runBoot, type RealmBootHandle } from "./boot.ts";
+import type { CompileFixture, CompileResult } from "./types.ts";
+
+// `t` inside a `Realm.describe` test is a Deno `TestContext` with two
+// extra methods: `compile` (single-app pipeline → resolved state) and
+// `boot` (full docker stack + Playwright sidecar). It extends rather
+// than wraps because authors pass the same `t` to `assertSnapshot` /
+// `t.step`, which want a real TestContext.
+export type RealmTestContext<App> = Deno.TestContext & {
+  compile(fixture: CompileFixture<App>): Promise<CompileResult>;
+  boot(fixture: CompileFixture<App>): Promise<RealmBootHandle>;
+};
+
+interface TestFn<App> {
+  (name: string, fn: (t: RealmTestContext<App>) => void | Promise<void>): void;
+  /**
+   * Register a tier-2 e2e test. Auto-skipped unless `REALM_TEST_E2E=1`
+   * is set (the `realm-sdk test --e2e` flag does this for you).
+   * Inside the body, call `t.boot(fixture)` to bring the stack up.
+   */
+  e2e(name: string, fn: (t: RealmTestContext<App>) => void | Promise<void>): void;
+}
+
+interface DescribeArgs<App> {
+  test: TestFn<App>;
+}
+
+function describe<TSchema extends ConfigSchema>(
+  app: AppDefinition<TSchema>,
+  sourceUrl: string,
+  body: (args: DescribeArgs<AppDefinition<TSchema>>) => void,
+): void {
+  type App = AppDefinition<TSchema>;
+  let bundledCodePromise: Promise<string> | undefined;
+  const ensureBundle = (): Promise<string> => {
+    if (!bundledCodePromise) {
+      bundledCodePromise = (async () => {
+        const path = sourceUrl.startsWith("file://") ? fromFileUrl(sourceUrl) : sourceUrl;
+        // Merge the app dir rather than reading the entry alone: a multi-file
+        // app's entry can import relative helpers, which have to be inlined
+        // before bundle() sees them (it blocks relative specifiers). Same merge
+        // dev and Home's install run, so a test compiles what Home ships.
+        const source = (await mergeSurfaces(dirname(path), basename(path))).source;
+        return bundle(source);
+      })();
+    }
+    return bundledCodePromise;
+  };
+
+  // Drives the test lifecycle: a per-test cleanup queue that each `t.boot`
+  // stack registers against, drained LIFO once the body resolves or throws.
+  // Authors never call `teardown()` themselves.
+  const runWithCleanup = async (
+    denoCtx: Deno.TestContext,
+    fn: (t: RealmTestContext<App>) => void | Promise<void>,
+  ): Promise<void> => {
+    const cleanups: Array<() => Promise<void>> = [];
+    const ctx = denoCtx as RealmTestContext<App>;
+    ctx.compile = async (fixture) => {
+      const bundledCode = await ensureBundle();
+      return runCompile<App>({ bundledCode, appName: app.name, fixture });
+    };
+    ctx.boot = async (fixture) => {
+      const bundledCode = await ensureBundle();
+      const { handle, cleanup } = await runBoot<App>({
+        bundledCode,
+        appName: app.name,
+        fixture,
+      });
+      cleanups.push(cleanup);
+      return handle;
+    };
+    try {
+      await fn(ctx);
+    } finally {
+      // LIFO so a test that booted A then B sees B torn down first.
+      // Errors during cleanup are swallowed so a flaky teardown can't
+      // mask the real test failure.
+      for (let i = cleanups.length - 1; i >= 0; i--) {
+        await cleanups[i]!().catch(() => {});
+      }
+    }
+  };
+
+  const test = ((testName, fn) => {
+    Deno.test(testName, (denoCtx) => runWithCleanup(denoCtx, fn));
+  }) as TestFn<App>;
+
+  test.e2e = (testName, fn) => {
+    const register = Deno.env.get("REALM_TEST_E2E") === "1" ? Deno.test : Deno.test.ignore;
+    register(testName, (denoCtx) => runWithCleanup(denoCtx, fn));
+  };
+
+  body({ test });
+}
+
+export const Realm = { describe };

package/src/test/index.ts

@@ -0,0 +1,11 @@
+// `@yourrealm/sdk/test` — author-facing test harness.
+//
+// Authors import `Realm` and the inferred `ConfigOf` / `GrantsOf` types
+// here. Home-side primitives (sanitizeGrants, the eval graph, etc.) stay
+// on `/home` — this entry only carries what a realm.ts test needs.
+
+export { Realm } from "./describe.ts";
+export type { RealmTestContext } from "./describe.ts";
+export type { RealmBootHandle } from "./boot.ts";
+export type { CompileFixture, CompileResult, ConfigOf, GrantsOf, CompileIssue } from "./types.ts";
+export type { WorldEntry, WorldState } from "../peer-world.ts";

package/src/test/ingress-fixture.ts

@@ -0,0 +1,37 @@
+// The `WorkerState.ingress` a harness-rendered box gets.
+//
+// `realm-sdk test --e2e` and `realm-sdk dev` both build a one-app WorkerState
+// in process and hand it to a renderer. Neither has a Home, so the values come
+// from the compile fixture's `management` block - the same Home identity
+// `host.management()` resolves from, so a fixture that sets `baseDomain`
+// describes a box whose ingress knows its own domain.
+//
+// `routedApps` is always empty: the harness boots one app and no proxy, so
+// there is nothing routing to anything.
+
+import type { IngressInput } from "../worker-protocol/ingress.ts";
+import type { CompileFixture } from "./types.ts";
+
+export function fixtureIngressInput(
+  management: CompileFixture<unknown>["management"],
+): IngressInput {
+  const baseDomain = management?.baseDomain ?? "";
+  const workerId = management?.workerId ?? "";
+  const homeSlug = management?.homeSlug ?? "";
+  const acmeDns = management?.acmeDns ?? null;
+  return {
+    routedApps: [],
+    // Null unless the fixture describes a full Home identity: `dashboardHost`
+    // names the box that runs Home, and a fixture with blank identity fields
+    // describes one that does not.
+    dashboardHost:
+      homeSlug && workerId && baseDomain ? `${homeSlug}.${workerId}.${baseDomain}` : null,
+    workerId,
+    baseDomain,
+    acmeDns: acmeDns ? { baseDomain, ...acmeDns } : null,
+    publicProviders: [],
+    cdnProviders: [],
+    // No operator to set them: the harness's statement matches no app.
+    companionFingerprints: [],
+  };
+}