@crowdedkingdoms/construct 0.3.2-dev.1 → 0.3.4-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/construct",
-  "version": "0.3.2-dev.1",
+  "version": "0.3.4-dev.1",
   "description": "The Construct framework: the Crowded Kingdoms game platform layer (hosted sign-in, World Stores, voice/webcam/chat, Crowdy Studio dock, app and grid mods, grid programs) and engine loop, shared by the-construct starter and the games built on it. Ships TypeScript source for Vite.",
   "license": "MIT",
   "type": "module",
@@ -45,8 +45,8 @@
     "./grid/*": "./src/grid/*.ts"
   },
   "peerDependencies": {
-    "@crowdedkingdoms/crowdyjs": ">=18.0.0-dev.0 <19 || >=18.0.1-dev.0 <19",
-    "@crowdedkingdoms/crowdy-dsh": ">=0.4.0-dev.0 <1 || >=0.4.1-dev.0 <1 || >=0.4.2-dev.0 <1"
+    "@crowdedkingdoms/crowdyjs": ">=18.0.4-dev.0 <19",
+    "@crowdedkingdoms/crowdy-dsh": ">=0.4.0-dev.0 <1 || >=0.4.1-dev.0 <1 || >=0.4.2-dev.0 <1 || >=0.4.3-dev.0 <1"
   },
   "peerDependenciesMeta": {
     "@crowdedkingdoms/crowdy-dsh": {

package/src/index.ts

@@ -92,4 +92,14 @@ export {
   type GridClientHalvesOptions,
 } from './platform/studio/clientHalves';
 export { gridServerCalls, type GridServerCallsOptions } from './platform/studio/gridServerCalls';
+export {
+  EXHAUSTED_MESSAGE,
+  REFUSED_MESSAGE,
+  describeWriteBackFailure,
+  guardWriteBacks,
+  reloadChunk,
+  type GuardedChunkStore,
+  type WriteBackGuardOptions,
+  type WriteBackTone,
+} from './platform/realtime/writeBackGuard';
 export { GridProgramRunner, type GridProgramRunnerOptions } from './grid/GridProgramRunner';

package/src/platform/GameSession.ts

@@ -18,6 +18,7 @@ import {
   type RemotePlayer,
   type SaveState,
 } from './realtime/WorldStores';
+import { guardWriteBacks, type WriteBackTone } from './realtime/writeBackGuard';
 import { WebcamService } from './media/WebcamService';
 import { VoiceService } from './media/VoiceService';
 import { ModelService } from './model/ModelService';
@@ -125,6 +126,22 @@ export class GameSession {
     return this.joinedFlag;
   }
 
+  /**
+   * Undo each chunk write-back the server refuses (or never accepts) and tell
+   * the player through `notify`. @returns off.
+   */
+  guardWriteBacks(notify: (text: string, tone: WriteBackTone) => void): () => void {
+    return guardWriteBacks(this.world.chunks, {
+      onServer: async (coord) =>
+        (await this.network.game.chunks.get({
+          appId: this.appId,
+          coordinates: chunkInput(coord),
+        })) != null,
+      notify,
+      log: (message) => this.network.log(message),
+    });
+  }
+
   /** The World Stores session for this app (lazily created). */
   get world(): ConstructWorldSession {
     return worldSession();

package/src/platform/realtime/writeBackGuard.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ChunkStore } from '@crowdedkingdoms/crowdyjs/stores';
+
+import {
+  EXHAUSTED_MESSAGE,
+  REFUSED_MESSAGE,
+  describeWriteBackFailure,
+  guardWriteBacks,
+} from './writeBackGuard';
+
+const COORD = { x: 2, y: 0, z: 3 };
+
+function base64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+function forbidden(): Error {
+  return Object.assign(new Error('You cannot edit this chunk'), {
+    extensions: { code: 'FORBIDDEN' },
+  });
+}
+
+/** The real SDK store over a fake client: `serverVoxels` is the server's copy (null: never stored). */
+function storeWith(update: () => Promise<unknown>, serverVoxels: Uint8Array | null) {
+  const client = {
+    chunks: {
+      update: vi.fn(update),
+      get: vi.fn(async () =>
+        serverVoxels ? { voxels: base64(serverVoxels), voxelStates: [] } : null,
+      ),
+      byDistance: vi.fn(async () => ({ chunks: [] })),
+    },
+    udp: { sendVoxelUpdate: vi.fn(async () => true) },
+  };
+  const ctx = {
+    appId: '1',
+    client,
+    ticker: { every: () => () => undefined },
+    on: () => () => undefined,
+    trackSend: () => undefined,
+    setSendTracker: () => undefined,
+    onDispose: () => undefined,
+  };
+  const store = new ChunkStore(ctx as never, { writeBackIntervalMs: false });
+  return { store, client };
+}
+
+async function paint(store: ChunkStore, voxelType: number): Promise<void> {
+  await store.setVoxel({ chunk: COORD, x: 1, y: 0, z: 1, voxelType, state: 'AA==' });
+  store.markDirty(COORD);
+}
+
+describe('guardWriteBacks', () => {
+  it('undoes a refused paint on a chunk the server never stored, once, and says so', async () => {
+    const { store, client } = storeWith(() => Promise.reject(forbidden()), null);
+    store.seed(COORD, new Uint8Array(4096), { writeBack: false });
+    const notify = vi.fn();
+    const off = guardWriteBacks(store, {
+      onServer: async () => (await client.chunks.get()) != null,
+      notify,
+    });
+
+    await paint(store, 5);
+    expect(store.voxelTypeAt(COORD, 1, 0, 1)).toBe(5);
+
+    const dropped = await store.flush();
+    expect(dropped).toHaveLength(1);
+    expect(dropped[0]?.reason).toBe('refused');
+    // Sent once, not retried.
+    expect(client.chunks.update).toHaveBeenCalledTimes(1);
+    expect(notify).toHaveBeenCalledWith(REFUSED_MESSAGE, 'warn');
+
+    await vi.waitFor(() => expect(store.voxelTypeAt(COORD, 1, 0, 1)).toBe(0));
+    expect(store.voxelStateAt(COORD, 1, 0, 1)).toBeUndefined();
+    expect(store.get(COORD)?.dirty).toBe(false);
+    expect(store.pendingWriteBacks).toBe(0);
+    off();
+  });
+
+  it("puts a refused chunk back to the server's copy", async () => {
+    const server = new Uint8Array(4096);
+    server[1 + 256] = 3;
+    const { store, client } = storeWith(() => Promise.reject(forbidden()), server);
+    store.seed(COORD, server.slice(), { writeBack: false });
+    guardWriteBacks(store, {
+      onServer: async () => (await client.chunks.get()) != null,
+      notify: () => undefined,
+    });
+
+    await paint(store, 7);
+    await store.flush();
+
+    await vi.waitFor(() => expect(store.voxelTypeAt(COORD, 1, 0, 1)).toBe(3));
+  });
+
+  it('says it once for a stroke that drops several chunks', async () => {
+    const { store } = storeWith(() => Promise.reject(forbidden()), null);
+    let now = 1_000;
+    const notify = vi.fn();
+    guardWriteBacks(store, { onServer: async () => false, notify, now: () => now });
+
+    for (const x of [0, 1, 2]) {
+      const coord = { x, y: 0, z: 0 };
+      store.seed(coord, new Uint8Array(4096), { writeBack: false });
+      store.markDirty(coord);
+    }
+    await store.flush();
+    expect(notify).toHaveBeenCalledTimes(1);
+
+    now += 5_000;
+    store.markDirty({ x: 0, y: 0, z: 0 });
+    await store.flush();
+    expect(notify).toHaveBeenCalledTimes(2);
+  });
+
+  it('logs the refusal and survives a failed reload', async () => {
+    const { store } = storeWith(() => Promise.reject(forbidden()), null);
+    store.seed(COORD, new Uint8Array(4096), { writeBack: false });
+    const log = vi.fn();
+    guardWriteBacks(store, {
+      onServer: () => Promise.reject(new Error('offline')),
+      notify: () => undefined,
+      log,
+    });
+    await paint(store, 5);
+    await store.flush();
+    await vi.waitFor(() => expect(log).toHaveBeenCalledWith('chunk 2,0,3 reload failed: offline'));
+    expect(log).toHaveBeenCalledWith(
+      'chunk 2,0,3 write-back refused after 1 attempt(s): You cannot edit this chunk',
+    );
+  });
+});
+
+describe('describeWriteBackFailure', () => {
+  it('tells a refusal from a server that did not answer', () => {
+    expect(describeWriteBackFailure({ reason: 'refused' })).toEqual({
+      text: REFUSED_MESSAGE,
+      tone: 'warn',
+    });
+    expect(describeWriteBackFailure({ reason: 'exhausted' })).toEqual({
+      text: EXHAUSTED_MESSAGE,
+      tone: 'error',
+    });
+  });
+});

package/src/platform/realtime/writeBackGuard.ts

@@ -0,0 +1,101 @@
+/**
+ * What the game does when a chunk write-back is dropped.
+ *
+ * `ChunkStore` applies a voxel edit locally at once and saves the chunk later
+ * (`markDirty` -> `chunks.update`). The server refuses that save for a player
+ * without edit permission on the chunk (another player's claim, a safe zone, a
+ * closed wilderness); the store sends a refusal once, retries anything else a
+ * few times, then drops it and reports it through `onWriteBackFailed`. It does
+ * not undo the local edit, so without this the player keeps seeing blocks
+ * nobody else has and that are gone on the next load.
+ *
+ * The guard puts the chunk back to the server's copy and tells the player.
+ * Paint, the holodeck and CLIENT `voxel_set` all write through the one store,
+ * and `flush()` reports what it dropped through the same listener, so one guard
+ * per world session covers every path.
+ */
+import { CHUNK_VOLUME, type ChunkWriteBackFailure } from '@crowdedkingdoms/crowdyjs/stores';
+
+import type { ChunkCoord } from './space';
+
+/** One stroke across a refused plot drops several chunks; say it once. */
+const NOTIFY_QUIET_MS = 4_000;
+
+export type WriteBackTone = 'info' | 'warn' | 'error';
+
+/** The slice of `ChunkStore` the guard uses. */
+export interface GuardedChunkStore {
+  onWriteBackFailed(
+    listener: (failure: ChunkWriteBackFailure<unknown, unknown>) => void,
+  ): () => void;
+  get(coord: ChunkCoord): { voxelStates: Map<number, unknown> } | undefined;
+  hydrate(coord: ChunkCoord): Promise<void>;
+  seed(coord: ChunkCoord, voxels: Uint8Array, options?: { writeBack?: boolean }): void;
+}
+
+export interface WriteBackGuardOptions {
+  /** Whether the server stores the chunk (`client.chunks.get` is not null). */
+  onServer(coord: ChunkCoord): Promise<boolean>;
+  notify(text: string, tone: WriteBackTone): void;
+  log?(message: string): void;
+  now?(): number;
+}
+
+export const REFUSED_MESSAGE =
+  "You can't build here: this area is someone else's claim or a protected zone. Your change was undone.";
+export const EXHAUSTED_MESSAGE =
+  "Your change couldn't be saved (the server didn't answer), so it was undone. Try again in a moment.";
+
+/** The player-facing line for a dropped write-back. */
+export function describeWriteBackFailure(failure: Pick<ChunkWriteBackFailure, 'reason'>): {
+  text: string;
+  tone: WriteBackTone;
+} {
+  return failure.reason === 'refused'
+    ? { text: REFUSED_MESSAGE, tone: 'warn' }
+    : { text: EXHAUSTED_MESSAGE, tone: 'error' };
+}
+
+/**
+ * Put a chunk back to the server's copy: hydrate it when the server stores it,
+ * else back to the empty chunk The Construct seeds for a never-written one.
+ */
+export async function reloadChunk(
+  chunks: GuardedChunkStore,
+  coord: ChunkCoord,
+  onServer: (coord: ChunkCoord) => Promise<boolean>,
+): Promise<void> {
+  const stored = await onServer(coord);
+  chunks.get(coord)?.voxelStates.clear();
+  if (stored) await chunks.hydrate(coord);
+  else chunks.seed(coord, new Uint8Array(CHUNK_VOLUME), { writeBack: false });
+}
+
+/** Undo and report every write-back the store drops. @returns off. */
+export function guardWriteBacks(
+  chunks: GuardedChunkStore,
+  options: WriteBackGuardOptions,
+): () => void {
+  const now = options.now ?? (() => Date.now());
+  let lastText = '';
+  let lastAt = -Infinity;
+  return chunks.onWriteBackFailed((failure) => {
+    const { coord } = failure;
+    const where = `${coord.x},${coord.y},${coord.z}`;
+    options.log?.(
+      `chunk ${where} write-back ${failure.reason} after ${failure.attempts} attempt(s): ${errorText(failure.error)}`,
+    );
+    const { text, tone } = describeWriteBackFailure(failure);
+    const at = now();
+    if (text !== lastText || at - lastAt >= NOTIFY_QUIET_MS) options.notify(text, tone);
+    lastText = text;
+    lastAt = at;
+    void reloadChunk(chunks, coord, options.onServer).catch((error) =>
+      options.log?.(`chunk ${where} reload failed: ${errorText(error)}`),
+    );
+  });
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/platform/studio/StudioService.ts

@@ -68,6 +68,8 @@ export interface StudioState {
   clientModsAvailable: boolean;
   /** The grid's CLIENT halves running for this player. */
   clientModsRunning: number;
+  /** Those CLIENT halves, for the controls that take them back. */
+  clientHalves: readonly RunningClientHalf[];
   /** Why CLIENT mods are unavailable, when they are. */
   clientModsReason: string | null;
   /** Agent dock mounted (policy + permission + host). */
@@ -76,6 +78,17 @@ export interface StudioState {
   agentReason: string | null;
 }
 
+/** A CLIENT half running for this player, and whose it is. */
+export interface RunningClientHalf {
+  modId: string;
+  name: string;
+  authorId: string;
+  /** The grid owner's display name, when the game knows it. */
+  authorName: string | null;
+  /** Written by this player (their own grid, not installed from a listing). */
+  own: boolean;
+}
+
 export interface StudioHooks {
   suppressGameplayInput(): () => void;
   onLayoutChange(rightInsetPx: number): void;
@@ -179,6 +192,7 @@ export class StudioService {
       grid: null,
       clientModsAvailable: CLIENT_MODS_ENABLED && isolated,
       clientModsRunning: 0,
+      clientHalves: [],
       clientModsReason: !CLIENT_MODS_ENABLED
         ? 'CLIENT mods are disabled in this build (VITE_CONSTRUCT_CLIENT_MODS=0).'
         : isolated
@@ -326,6 +340,37 @@ export class StudioService {
     this.openOn(grid);
   }
 
+  /** "Stop running this": the player takes back their consent to one CLIENT half here. */
+  async stopClientHalf(modId: string): Promise<void> {
+    await this.takeBack(`stopped the CLIENT half of mod ${modId}`, (halves) =>
+      halves.revoke(modId),
+    );
+  }
+
+  /** "Forget this author": the player takes back their trust in an author on this grid. */
+  async forgetClientHalfAuthor(authorId: string): Promise<void> {
+    await this.takeBack(`forgot author ${authorId} on this grid`, (halves) =>
+      halves.forgetAuthor(authorId),
+    );
+  }
+
+  private async takeBack(
+    done: string,
+    work: (halves: GridClientHalves) => Promise<boolean>,
+  ): Promise<void> {
+    const halves = this.halves;
+    if (!halves) return;
+    try {
+      await work(halves);
+      this.session.network.log(`CLIENT halves: ${done}`);
+    } catch (error) {
+      this.hooks?.notify(
+        `Stopped here, but the platform did not record it (${messageOf(error)}); it may run on your next visit.`,
+        'warn',
+      );
+    }
+  }
+
   close(): void {
     this.embed?.close();
     if (this.currentGrid) {
@@ -461,7 +506,18 @@ export class StudioService {
         }),
       filter: (mod) => !this.previewedByStudio(mod),
       onChange: (running) => {
-        this.state = { ...this.state, clientModsRunning: running.length };
+        const self = this.session.network.user?.userId ?? null;
+        const clientHalves = running.map((mod) => ({
+          modId: String(mod.modId),
+          name: mod.name,
+          authorId: String(mod.authorId),
+          authorName:
+            this.currentGrid?.gridId === String(mod.gridId)
+              ? (this.currentGrid.ownerName ?? null)
+              : null,
+          own: self !== null && String(mod.authorId) === String(self) && mod.listingId == null,
+        }));
+        this.state = { ...this.state, clientModsRunning: running.length, clientHalves };
         this.emit();
       },
       log: (line) => this.session.network.log(line),

package/src/platform/studio/clientHalves.test.ts

@@ -16,6 +16,7 @@ vi.mock('@crowdedkingdoms/crowdyjs/crowdy-studio', async () => {
 const {
   GridClientHalves,
   clientHalfSource,
+  describeClientCapabilities,
   describeClientHalfPrompt,
   isOwnClientHalfPrompt,
   studioPreviewModName,
@@ -73,6 +74,8 @@ function harness(
     gridClientMods: vi.fn(async () => listings[Math.min(listed++, listings.length - 1)]!),
     consentClientMod: vi.fn(async () => true),
     trustAuthor: vi.fn(async () => true),
+    revokeClientModConsent: vi.fn(async () => true),
+    revokeAuthorTrust: vi.fn(async () => true),
     modClientArtifactBytes: vi.fn(async (_appId: string, modId: string) => {
       const mod = listings.flat().find((m) => m.modId === modId)!;
       return {
@@ -166,6 +169,31 @@ describe('GridClientHalves', () => {
     expect(h.serverCalls).toHaveBeenCalledWith(GRID);
   });
 
+  it('stops a CLIENT half the player takes back, and forgets its author, through the game client', async () => {
+    const h = harness({
+      listings: [
+        [
+          half({ callerConsented: true }),
+          half({ modId: 'm2', name: 'shop', digest: 'd2', callerConsented: true }),
+        ],
+      ],
+    });
+    h.halves.enterGrid(GRID);
+    await h.halves.refresh();
+    expect(h.halves.running.map((m) => m.modId)).toEqual(['m1', 'm2']);
+
+    await expect(h.halves.revoke('m1')).resolves.toBe(true);
+    expect(h.exec.revokeClientModConsent).toHaveBeenCalledWith('1', 'm1');
+    expect(h.halves.running.map((m) => m.modId)).toEqual(['m2']);
+    expect(h.hud.remove).toHaveBeenCalledWith('grid:m1');
+
+    await expect(h.halves.forgetAuthor('7')).resolves.toBe(true);
+    expect(h.exec.revokeAuthorTrust).toHaveBeenCalledWith('1', '42', '7');
+    expect(h.halves.running).toEqual([]);
+    await h.halves.refresh();
+    expect(h.halves.running).toEqual([]);
+  });
+
   it("forwards a CLIENT half's log lines and invokes its handle_invoke", async () => {
     const lines: string[] = [];
     const h = harness({ log: (line) => lines.push(line) });
@@ -298,6 +326,20 @@ describe('client half prompts', () => {
     expect(text).toContain('Installed from the marketplace: shop.');
     expect(text).toContain('• host calls: hud_set, actors_list, user_state_get');
     expect(text).toContain('• groups: present, world_read, state');
+    expect(text).toContain('• it can read your saved state in this game');
+    expect(text).not.toContain('replace your saved state');
+  });
+
+  it('says in plain words what the calls that act as the player can do', () => {
+    const summary = {
+      ...SUMMARY,
+      hostFunctions: ['user_state_set', 'voxel_set', 'emit_spatial', 'constructor'],
+    };
+    const text = describeClientCapabilities(summary as never, JSON.stringify(summary));
+    expect(text).toContain('• it can replace your saved state in this game');
+    expect(text).toContain('• it can change blocks on this grid as you');
+    expect(text).toContain('• it can send messages and effects to players near you');
+    expect(text.split('\n').filter((line) => line.startsWith('• it can'))).toHaveLength(3);
   });
 
   it('asks about one CLIENT half, and shows a summary that does not parse as it is', () => {

package/src/platform/studio/clientHalves.ts

@@ -41,7 +41,12 @@ import type { ModOverlayStore } from './modOverlay';
 
 export type ClientHalvesExec = Pick<
   ExecAPI,
-  'gridClientMods' | 'consentClientMod' | 'trustAuthor' | 'modClientArtifactBytes'
+  | 'gridClientMods'
+  | 'consentClientMod'
+  | 'trustAuthor'
+  | 'modClientArtifactBytes'
+  | 'revokeClientModConsent'
+  | 'revokeAuthorTrust'
 >;
 
 /** The grid the player stands in: its id and chunk box. */
@@ -105,6 +110,9 @@ export class GridClientHalves {
         trustAuthor: (appId, gridId, authorId, hash) =>
           exec().trustAuthor(appId, gridId, authorId, hash),
         modClientArtifactBytes: (appId, modId) => exec().modClientArtifactBytes(appId, modId),
+        revokeClientModConsent: (appId, modId) => exec().revokeClientModConsent(appId, modId),
+        revokeAuthorTrust: (appId, gridId, authorId) =>
+          exec().revokeAuthorTrust(appId, gridId, authorId),
       },
       appId: options.appId,
       workerUrl: options.workerUrl,
@@ -162,6 +170,24 @@ export class GridClientHalves {
     return this.runner.invoke(modId, payload, options);
   }
 
+  /**
+   * "Stop running this": stops the CLIENT half of mod `modId` and takes back the player's consent
+   * to it (and their trust in its author, when it ran through that trust, keeping the author's
+   * other halves). Not asked about again on this grid until it changes. Rejects when the platform
+   * refuses; the half stays stopped here.
+   */
+  revoke(modId: string): Promise<boolean> {
+    return this.runner.revoke(modId);
+  }
+
+  /**
+   * "Forget this author": stops every CLIENT half of `authorId` on this grid and takes back the
+   * player's trust in them here, with every consent to their halves.
+   */
+  forgetAuthor(authorId: string): Promise<boolean> {
+    return this.runner.forgetAuthor(authorId);
+  }
+
   stop(): void {
     this.asking?.abort();
     this.asking = null;
@@ -273,6 +299,16 @@ export function describeClientHalfPrompt(
   return lines.join('\n');
 }
 
+/** What the host calls that act as the player let a CLIENT half do, in the player's words. */
+const ACTS_AS_YOU: Record<string, string> = {
+  user_state_get: 'read your saved state in this game',
+  user_state_set: 'replace your saved state in this game',
+  voxel_set: 'change blocks on this grid as you',
+  emit_spatial: 'send messages and effects to players near you, from your game',
+  emit_channel: "post in this grid's channels, from your game",
+  pointer_clicks: 'see your mouse clicks',
+};
+
 export function describeClientCapabilities(
   summary: ExecClientCapabilitySummary | null,
   json: string,
@@ -284,6 +320,9 @@ export function describeClientCapabilities(
   if (summary.capabilityGroups.length > 0) {
     rows.push(`• groups: ${summary.capabilityGroups.join(', ')}`);
   }
+  for (const fn of summary.hostFunctions) {
+    if (Object.hasOwn(ACTS_AS_YOU, fn)) rows.push(`• it can ${ACTS_AS_YOU[fn]}`);
+  }
   return rows.join('\n');
 }
 

package/src/platform/studio/clientModHost.test.ts

@@ -185,6 +185,54 @@ describe('routeClientHostCall', () => {
     ]);
   });
 
+  it('writes no voxel outside the grid, whatever second chunk the call carries', async () => {
+    const r = reads();
+    const written: Array<{ chunk: { x: number; y: number; z: number } }> = [];
+    const writes = {
+      setVoxel: async (input: { chunk: { x: number; y: number; z: number } }) => {
+        written.push(input);
+        return true;
+      },
+    };
+    const voxel = { voxelX: 1, voxelY: 0, voxelZ: 2, voxelType: 7 };
+    // The broker checks chunkX/Y/Z against the grid; a call must not steer the write elsewhere.
+    for (const args of [
+      { chunkX: 0, chunkY: 0, chunkZ: 0, chunk: { x: 999, y: 0, z: 0 }, ...voxel },
+      { chunkX: 0, chunkY: 0, chunkZ: 0, chunk: [999, 0, 0], ...voxel },
+      { chunkX: 0, chunkY: 0, chunkZ: 0, chunk_x: 999, ...voxel },
+    ]) {
+      await routeClientHostCall({ fn: 'voxel_set', args } as never, r.reads, grid, writes);
+    }
+    expect(written.map((w) => w.chunk)).toEqual([
+      { x: 0, y: 0, z: 0 },
+      { x: 0, y: 0, z: 0 },
+      { x: 0, y: 0, z: 0 },
+    ]);
+    // Named only the second way, the chunk is checked against the grid at the write.
+    for (const args of [
+      { chunk: { x: 999, y: 0, z: 0 }, ...voxel },
+      { chunk_x: 5, chunk_y: 0, chunk_z: 0, ...voxel },
+      { chunkX: 2, chunkY: 0, chunkZ: 0, ...voxel },
+    ]) {
+      expect(
+        await routeClientHostCall({ fn: 'voxel_set', args } as never, r.reads, grid, writes),
+      ).toEqual({ ok: false, error: 'out_of_grid' });
+    }
+    expect(written.length).toBe(3);
+  });
+
+  it('refuses voxel_set without the grid to confine it to', async () => {
+    const r = reads();
+    await expect(
+      routeClientHostCall(
+        { fn: 'voxel_set', args: { chunkX: 0, chunkY: 0, chunkZ: 0, voxelType: 1 } } as never,
+        r.reads,
+        undefined,
+        { setVoxel: async () => true },
+      ),
+    ).rejects.toBeInstanceOf(HostCallRefusedError);
+  });
+
   it('parses flattened chunkX host-call args the broker clamps', () => {
     expect(
       parseVoxelSetArgs({

package/src/platform/studio/clientModHost.ts

@@ -110,9 +110,10 @@ export async function routeClientHostCall(
         : { voxels: voxelsFromBase64(chunk.voxelsBase64) };
     }
     case 'voxel_set': {
-      if (!writes) throw new HostCallRefusedError(fn);
+      if (!writes || !grid) throw new HostCallRefusedError(fn);
       const parsed = parseVoxelSetArgs(args);
       if (!parsed) return { ok: false, error: 'invalid voxel_set arguments' };
+      if (!chunkInGrid(parsed.chunk, grid)) return { ok: false, error: 'out_of_grid' };
       const ok = await writes.setVoxel({
         chunk: parsed.chunk,
         x: parsed.x,
@@ -163,7 +164,11 @@ function asCoord3(value: unknown): { x: unknown; y: unknown; z: unknown } | null
   return null;
 }
 
-/** Accept the SDKs' flattened host-call JSON (the broker clamps its chunk) and the tuple shape. */
+/**
+ * Accept the SDKs' flattened host-call JSON and the tuple shape. The chunk is `chunkX/Y/Z`, the
+ * fields the broker checks against the grid, whenever any of them is present; `args.chunk` only
+ * when none is. The caller still checks the chunk against the grid.
+ */
 export function parseVoxelSetArgs(args: Record<string, unknown>): {
   chunk: { x: number; y: number; z: number };
   x: number;
@@ -172,13 +177,15 @@ export function parseVoxelSetArgs(args: Record<string, unknown>): {
   voxelType: number;
   state: string;
 } | null {
-  const chunkRaw =
-    asCoord3(args.chunk) ??
-    ({
-      x: coordField(args, 'chunkX', 'chunk_x'),
-      y: coordField(args, 'chunkY', 'chunk_y'),
-      z: coordField(args, 'chunkZ', 'chunk_z'),
-    } as { x: unknown; y: unknown; z: unknown });
+  const flat = ['chunkX', 'chunkY', 'chunkZ'].some((key) => args[key] !== undefined);
+  const chunkRaw = flat
+    ? { x: args.chunkX, y: args.chunkY, z: args.chunkZ }
+    : (asCoord3(args.chunk) ??
+      ({
+        x: coordField(args, 'chunk_x'),
+        y: coordField(args, 'chunk_y'),
+        z: coordField(args, 'chunk_z'),
+      } as { x: unknown; y: unknown; z: unknown }));
   const voxelRaw =
     asCoord3(args.voxel) ??
     ({
@@ -248,6 +255,23 @@ export async function routeWithFallback(
   }
 }
 
+function chunkInGrid(
+  chunk: { x: number; y: number; z: number },
+  grid: PlayerCodeGridBounds,
+): boolean {
+  const x = BigInt(chunk.x);
+  const y = BigInt(chunk.y);
+  const z = BigInt(chunk.z);
+  return (
+    x >= grid.low.x &&
+    x <= grid.high.x &&
+    y >= grid.low.y &&
+    y <= grid.high.y &&
+    z >= grid.low.z &&
+    z <= grid.high.z
+  );
+}
+
 function minBig(a: bigint, b: bigint): bigint {
   return a < b ? a : b;
 }