@flighthq/entity 0.3.0-next.906.07cea63 → 0.3.0

package/dist/contract.d.ts

@@ -1,6 +1,7 @@
 export * from './binding';
 export * from './clone';
 export * from './entity';
+export * from './enableEntityRuntimeGuards';
 export * from './guards';
 export * from './runtime';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/contract.js

@@ -1,6 +1,7 @@
 export * from './binding';
 export * from './clone';
 export * from './entity';
+export * from './enableEntityRuntimeGuards';
 export * from './guards';
 export * from './runtime';
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/enableEntityRuntimeGuards.d.ts

@@ -0,0 +1,3 @@
+export declare function disableEntityRuntimeGuards(): void;
+export declare function enableEntityRuntimeGuards(): void;
+//# sourceMappingURL=enableEntityRuntimeGuards.d.ts.map

package/dist/enableEntityRuntimeGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableEntityRuntimeGuards.d.ts","sourceRoot":"","sources":["../src/enableEntityRuntimeGuards.ts"],"names":[],"mappings":"AAOA,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD;AAWD,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD"}

package/dist/enableEntityRuntimeGuards.js

@@ -0,0 +1,33 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setEntityRuntimeGuardMode, setEntityRuntimeWriteGuard } from './guards';
+// Uninstalls the guard installed by enableEntityRuntimeGuards, restoring unguarded entities.
+export function disableEntityRuntimeGuards() {
+    setEntityRuntimeGuardMode(false);
+    setEntityRuntimeWriteGuard(null);
+}
+// Opt-in development guard mode. When enabled, a direct write to an entity's runtime slot — or to an
+// EntityRuntime's binding slot — that bypasses ensureEntityRuntime / attachEntityBinding is reported,
+// making "the write landed on the wrong entity" and raw-slot-poke bugs visible early. The write is still
+// allowed: the guard observes, it does not block.
+//
+// @flighthq/entity is a CORE package, and core may otherwise depend only on types/core. This module is the
+// sanctioned exception: it is separately importable and shakeable, so a build that never imports it never
+// pulls @flighthq/log, and the layer rule's real concern — feature weight in core's always-loaded graph —
+// does not arise. `packages:check` enforces that the import appears in guard modules only. Idempotent.
+export function enableEntityRuntimeGuards() {
+    setEntityRuntimeGuardMode(true);
+    setEntityRuntimeWriteGuard(warnOnDirectWrite);
+}
+function warnOnDirectWrite(slot) {
+    if (slot === 'binding-slot') {
+        logOnce('entity:direct-binding-write', LogLevel.Warn, {
+            message: 'EntityRuntime.binding was written directly. Use attachEntityBinding or detachEntityBinding, which keep the binding and the runtime consistent; the write was allowed but is not tracked.',
+        }, 'entity');
+        return;
+    }
+    logOnce('entity:direct-runtime-write', LogLevel.Warn, {
+        message: "An entity's runtime slot was written directly. Use ensureEntityRuntime or attachEntityBinding; the write was allowed, but bypassing them is how a runtime ends up on the wrong entity.",
+    }, 'entity');
+}
+//# sourceMappingURL=enableEntityRuntimeGuards.js.map

package/dist/enableEntityRuntimeGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableEntityRuntimeGuards.js","sourceRoot":"","sources":["../src/enableEntityRuntimeGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAEjF,6FAA6F;AAC7F,MAAM,UAAU,0BAA0B;IACxC,yBAAyB,CAAC,KAAK,CAAC,CAAC;IACjC,0BAA0B,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED,qGAAqG;AACrG,sGAAsG;AACtG,yGAAyG;AACzG,kDAAkD;AAClD,EAAE;AACF,2GAA2G;AAC3G,0GAA0G;AAC1G,0GAA0G;AAC1G,uGAAuG;AACvG,MAAM,UAAU,yBAAyB;IACvC,yBAAyB,CAAC,IAAI,CAAC,CAAC;IAChC,0BAA0B,CAAC,iBAAiB,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,iBAAiB,CAAC,IAA4B;IACrD,IAAI,IAAI,KAAK,cAAc,EAAE,CAAC;QAC5B,OAAO,CACL,6BAA6B,EAC7B,QAAQ,CAAC,IAAI,EACb;YACE,OAAO,EACL,0LAA0L;SAC7L,EACD,QAAQ,CACT,CAAC;QACF,OAAO;IACT,CAAC;IACD,OAAO,CACL,6BAA6B,EAC7B,QAAQ,CAAC,IAAI,EACb;QACE,OAAO,EACL,wLAAwL;KAC3L,EACD,QAAQ,CACT,CAAC;AACJ,CAAC"}

package/dist/guards.d.ts

@@ -1,6 +1,7 @@
-import type { Entity, EntityRuntime } from '@flighthq/types/contract';
+import type { Entity, EntityRuntime, EntityRuntimeWriteGuard } from '@flighthq/types/contract';
 export declare function areEntityRuntimeGuardsEnabled(): boolean;
 export declare function createGuardedEntity<Type extends object>(entity: Type & Entity): Type & Entity;
 export declare function createGuardedEntityRuntime(runtime: EntityRuntime): EntityRuntime;
-export declare function enableEntityRuntimeGuards(): void;
+export declare function setEntityRuntimeGuardMode(enabled: boolean): void;
+export declare function setEntityRuntimeWriteGuard(guard: EntityRuntimeWriteGuard | null): void;
 //# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAItE,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAmB7F;AAKD,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAehF;AASD,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAI/F,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAe7F;AAKD,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAWhF;AAID,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAGhE;AAID,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,GAAG,IAAI,CAEtF"}

package/dist/guards.js

@@ -12,12 +12,11 @@ export function createGuardedEntity(entity) {
     return new Proxy(entity, {
         set(target, prop, value) {
             if (prop === EntityRuntimeKey && _guardsEnabled) {
-                // Allow writes from trusted paths by checking the stack. Since we cannot reliably
-                // inspect the stack in all environments, we emit a warning and allow the write.
-                // In practice, ensureEntityRuntime and attachEntityBinding are the only callers that
-                // should write to this slot.
-                // eslint-disable-next-line no-console
-                console.warn('[entity] Direct write to EntityRuntimeKey detected. Use ensureEntityRuntime or attachEntityBinding instead.', entity);
+                // The write is reported and then ALLOWED: the stack cannot be inspected reliably across
+                // environments, so trusted callers (ensureEntityRuntime, attachEntityBinding) cannot be told apart
+                // from a raw poke. Reporting goes through the seam rather than the console so it uses the standard
+                // sink — see enableEntityRuntimeGuards.
+                _writeGuard?.('runtime-slot');
             }
             target[prop] = value;
             return true;
@@ -33,25 +32,25 @@ export function createGuardedEntityRuntime(runtime) {
     return new Proxy(runtime, {
         set(target, prop, value) {
             if (prop === 'binding' && _guardsEnabled) {
-                // eslint-disable-next-line no-console
-                console.warn('[entity] Direct write to EntityRuntime.binding detected. Use attachEntityBinding or detachEntityBinding instead.', runtime);
+                _writeGuard?.('binding-slot');
             }
             target[prop] = value;
             return true;
         },
     });
 }
-// Opt-in development guard mode. When enabled, direct writes to the EntityRuntimeKey slot
-// that bypass ensureEntityRuntime / attachEntityBinding will warn in the console, making
-// "writes landed on the wrong entity or raw slot poke" bugs visible early.
-//
-// This function is a no-op in production if the calling module is never imported — it is
-// fully tree-shakable, never called at module top level, and has no effect on
-// "sideEffects": false.
-export function enableEntityRuntimeGuards() {
-    if (typeof Proxy === 'undefined')
+// Turns the guarding PROXIES on or off. This is the machinery seam, not the caller-facing entry point —
+// use enableEntityRuntimeGuards, which switches this on and installs the reporter together.
+export function setEntityRuntimeGuardMode(enabled) {
+    if (enabled && typeof Proxy === 'undefined')
         return;
-    _guardsEnabled = true;
+    _guardsEnabled = enabled;
+}
+// The diagnostics seam for a direct slot write. Null uninstalls it, and null is what a build that never
+// imports the guard module sees — which is why this file needs no logger and stays inside the core layer.
+export function setEntityRuntimeWriteGuard(guard) {
+    _writeGuard = guard;
 }
 let _guardsEnabled = false;
+let _writeGuard = null;
 //# sourceMappingURL=guards.js.map

package/dist/guards.js.map

@@ -1 +1 @@
-{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,yFAAyF;AACzF,MAAM,UAAU,6BAA6B;IAC3C,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,uFAAuF;AACvF,uFAAuF;AACvF,yCAAyC;AACzC,MAAM,UAAU,mBAAmB,CAAsB,MAAqB;IAC5E,IAAI,CAAC,cAAc,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC;IACnE,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE;QACvB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK;YACrB,IAAI,IAAI,KAAK,gBAAgB,IAAI,cAAc,EAAE,CAAC;gBAChD,kFAAkF;gBAClF,gFAAgF;gBAChF,qFAAqF;gBACrF,6BAA6B;gBAC7B,sCAAsC;gBACtC,OAAO,CAAC,IAAI,CACV,6GAA6G,EAC7G,MAAM,CACP,CAAC;YACJ,CAAC;YACA,MAAkD,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,0FAA0F;AAC1F,2FAA2F;AAC3F,eAAe;AACf,MAAM,UAAU,0BAA0B,CAAC,OAAsB;IAC/D,IAAI,CAAC,cAAc,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC;IACpE,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE;QACxB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK;YACrB,IAAI,IAAI,KAAK,SAAS,IAAI,cAAc,EAAE,CAAC;gBACzC,sCAAsC;gBACtC,OAAO,CAAC,IAAI,CACV,kHAAkH,EAClH,OAAO,CACR,CAAC;YACJ,CAAC;YACA,MAAkD,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,0FAA0F;AAC1F,yFAAyF;AACzF,2EAA2E;AAC3E,EAAE;AACF,yFAAyF;AACzF,8EAA8E;AAC9E,wBAAwB;AACxB,MAAM,UAAU,yBAAyB;IACvC,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO;IACzC,cAAc,GAAG,IAAI,CAAC;AACxB,CAAC;AAED,IAAI,cAAc,GAAG,KAAK,CAAC"}
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,yFAAyF;AACzF,MAAM,UAAU,6BAA6B;IAC3C,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,uFAAuF;AACvF,uFAAuF;AACvF,yCAAyC;AACzC,MAAM,UAAU,mBAAmB,CAAsB,MAAqB;IAC5E,IAAI,CAAC,cAAc,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC;IACnE,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE;QACvB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK;YACrB,IAAI,IAAI,KAAK,gBAAgB,IAAI,cAAc,EAAE,CAAC;gBAChD,wFAAwF;gBACxF,mGAAmG;gBACnG,mGAAmG;gBACnG,wCAAwC;gBACxC,WAAW,EAAE,CAAC,cAAc,CAAC,CAAC;YAChC,CAAC;YACA,MAAkD,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,0FAA0F;AAC1F,2FAA2F;AAC3F,eAAe;AACf,MAAM,UAAU,0BAA0B,CAAC,OAAsB;IAC/D,IAAI,CAAC,cAAc,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC;IACpE,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE;QACxB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK;YACrB,IAAI,IAAI,KAAK,SAAS,IAAI,cAAc,EAAE,CAAC;gBACzC,WAAW,EAAE,CAAC,cAAc,CAAC,CAAC;YAChC,CAAC;YACA,MAAkD,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAClE,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,wGAAwG;AACxG,4FAA4F;AAC5F,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,IAAI,OAAO,IAAI,OAAO,KAAK,KAAK,WAAW;QAAE,OAAO;IACpD,cAAc,GAAG,OAAO,CAAC;AAC3B,CAAC;AAED,wGAAwG;AACxG,0GAA0G;AAC1G,MAAM,UAAU,0BAA0B,CAAC,KAAqC;IAC9E,WAAW,GAAG,KAAK,CAAC;AACtB,CAAC;AAED,IAAI,cAAc,GAAG,KAAK,CAAC;AAC3B,IAAI,WAAW,GAAmC,IAAI,CAAC"}

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/entity",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.0",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,7 +38,8 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/log": "0.3.0",
+    "@flighthq/types": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/enableEntityRuntimeGuards.test.ts

@@ -0,0 +1,73 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import type { LogEntry } from '@flighthq/types/contract';
+import { EntityRuntimeKey } from '@flighthq/types/contract';
+
+import { disableEntityRuntimeGuards, enableEntityRuntimeGuards } from './enableEntityRuntimeGuards';
+import { createEntity } from './entity';
+import { areEntityRuntimeGuardsEnabled, createGuardedEntity, createGuardedEntityRuntime } from './guards';
+import { createEntityRuntime } from './runtime';
+
+function captureLog(run: () => void): readonly LogEntry[] {
+  const sink = createMemoryLogSink(8);
+  addLogSink(sink.sink);
+  try {
+    run();
+    return getMemoryLogSinkEntries(sink);
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+function messageOf(entry: Readonly<LogEntry>): string {
+  const data = entry.data;
+  return typeof data === 'string' ? data : String(data.message);
+}
+
+describe('disableEntityRuntimeGuards', () => {
+  it('uninstalls both the proxies and the reporter', () => {
+    const entries = captureLog(() => {
+      enableEntityRuntimeGuards();
+      disableEntityRuntimeGuards();
+      createGuardedEntity(createEntity())[EntityRuntimeKey] = undefined;
+    });
+    expect(entries.length).toBe(0);
+    expect(areEntityRuntimeGuardsEnabled()).toBe(false);
+  });
+});
+
+describe('enableEntityRuntimeGuards', () => {
+  it('WARNS through the log sink on a direct runtime-slot write', () => {
+    const entries = captureLog(() => {
+      enableEntityRuntimeGuards();
+      try {
+        createGuardedEntity(createEntity())[EntityRuntimeKey] = undefined;
+      } finally {
+        disableEntityRuntimeGuards();
+      }
+    });
+    expect(entries.length).toBe(1);
+    expect(messageOf(entries[0])).toContain('ensureEntityRuntime');
+  });
+
+  it('WARNS separately for a direct binding-slot write', () => {
+    const entries = captureLog(() => {
+      enableEntityRuntimeGuards();
+      try {
+        createGuardedEntityRuntime(createEntityRuntime()).binding = null;
+      } finally {
+        disableEntityRuntimeGuards();
+      }
+    });
+    expect(entries.length).toBe(1);
+    expect(messageOf(entries[0])).toContain('attachEntityBinding');
+  });
+
+  it('stays SILENT without the guard — the production default', () => {
+    const entries = captureLog(() => {
+      // Unguarded entities are returned as-is, so there is nothing to intercept.
+      createGuardedEntity(createEntity())[EntityRuntimeKey] = undefined;
+    });
+    expect(entries.length).toBe(0);
+    expect(areEntityRuntimeGuardsEnabled()).toBe(false);
+  });
+});

package/src/guards.test.ts

@@ -1,16 +1,18 @@
 import { EntityRuntimeKey } from '@flighthq/types/contract';
+import type { EntityRuntimeWriteSlot } from '@flighthq/types/contract';
 
 import { createEntity } from './entity';
 import {
   areEntityRuntimeGuardsEnabled,
   createGuardedEntity,
   createGuardedEntityRuntime,
-  enableEntityRuntimeGuards,
+  setEntityRuntimeGuardMode,
+  setEntityRuntimeWriteGuard,
 } from './guards';
 import { createEntityRuntime } from './runtime';
 
 describe('areEntityRuntimeGuardsEnabled', () => {
-  it('returns false before enableEntityRuntimeGuards is called', () => {
+  it('returns false before guard mode is switched on', () => {
     // Vitest isolates modules per file, so this starts false in a fresh module import.
     expect(areEntityRuntimeGuardsEnabled()).toBe(false);
   });
@@ -19,46 +21,61 @@ describe('areEntityRuntimeGuardsEnabled', () => {
 describe('createGuardedEntity', () => {
   it('returns the entity unchanged when guards are not enabled', () => {
     const entity = createEntity({ x: 1 });
-    const guarded = createGuardedEntity(entity);
-    expect(guarded).toBe(entity);
+    expect(createGuardedEntity(entity)).toBe(entity);
   });
 });
 
 describe('createGuardedEntityRuntime', () => {
   it('returns the runtime unchanged when guards are not enabled', () => {
     const runtime = createEntityRuntime();
-    const guarded = createGuardedEntityRuntime(runtime);
-    expect(guarded).toBe(runtime);
+    expect(createGuardedEntityRuntime(runtime)).toBe(runtime);
   });
 });
 
-describe('enableEntityRuntimeGuards', () => {
-  it('enables guards', () => {
-    enableEntityRuntimeGuards();
-    expect(areEntityRuntimeGuardsEnabled()).toBe(true);
-  });
-
-  it('createGuardedEntity returns a proxy when guards are enabled', () => {
-    enableEntityRuntimeGuards();
-    const entity = createEntity({ x: 1 });
-    const guarded = createGuardedEntity(entity);
-    expect(guarded.x).toBe(1);
+describe('setEntityRuntimeGuardMode', () => {
+  it('switches the proxies on and back off', () => {
+    setEntityRuntimeGuardMode(true);
+    try {
+      expect(areEntityRuntimeGuardsEnabled()).toBe(true);
+      const entity = createEntity({ x: 1 });
+      expect(createGuardedEntity(entity).x).toBe(1);
+      expect(createGuardedEntityRuntime(createEntityRuntime()).binding).toBeNull();
+    } finally {
+      setEntityRuntimeGuardMode(false);
+    }
+    expect(areEntityRuntimeGuardsEnabled()).toBe(false);
   });
+});
 
-  it('createGuardedEntityRuntime returns a proxy when guards are enabled', () => {
-    enableEntityRuntimeGuards();
-    const runtime = createEntityRuntime();
-    const guarded = createGuardedEntityRuntime(runtime);
-    expect(guarded.binding).toBeNull();
+describe('setEntityRuntimeWriteGuard', () => {
+  it('reports which slot a direct write landed on, and still ALLOWS the write', () => {
+    const slots: EntityRuntimeWriteSlot[] = [];
+    setEntityRuntimeGuardMode(true);
+    setEntityRuntimeWriteGuard((slot) => slots.push(slot));
+    try {
+      const guardedEntity = createGuardedEntity(createEntity());
+      guardedEntity[EntityRuntimeKey] = undefined;
+      const guardedRuntime = createGuardedEntityRuntime(createEntityRuntime());
+      guardedRuntime.binding = null;
+      expect(slots).toEqual(['runtime-slot', 'binding-slot']);
+      // The guard observes; it does not block. The write must land.
+      expect(EntityRuntimeKey in guardedEntity).toBe(true);
+    } finally {
+      setEntityRuntimeWriteGuard(null);
+      setEntityRuntimeGuardMode(false);
+    }
   });
 
-  it('guarded entity warns on direct EntityRuntimeKey write', () => {
-    enableEntityRuntimeGuards();
-    const entity = createEntity();
-    const guarded = createGuardedEntity(entity);
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
-    guarded[EntityRuntimeKey] = undefined;
-    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('[entity]'), expect.anything());
-    warnSpy.mockRestore();
+  it('is silent once uninstalled', () => {
+    const slots: EntityRuntimeWriteSlot[] = [];
+    setEntityRuntimeGuardMode(true);
+    setEntityRuntimeWriteGuard((slot) => slots.push(slot));
+    setEntityRuntimeWriteGuard(null);
+    try {
+      createGuardedEntity(createEntity())[EntityRuntimeKey] = undefined;
+      expect(slots).toEqual([]);
+    } finally {
+      setEntityRuntimeGuardMode(false);
+    }
   });
 });