@flighthq/entity 0.1.0

package/dist/binding.d.ts

@@ -0,0 +1,4 @@
+import type { Entity } from '@flighthq/types';
+export declare function attachEntityBinding(entity: Entity, binding: object): void;
+export declare function getEntityBinding(source: Entity): object | null;
+//# sourceMappingURL=binding.d.ts.map

package/dist/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAK9C,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAKzE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D"}

package/dist/binding.js

@@ -0,0 +1,13 @@
+import { EntityRuntimeKey } from '@flighthq/types';
+import { createEntityRuntime, getEntityRuntime } from './runtime';
+export function attachEntityBinding(entity, binding) {
+    if (entity[EntityRuntimeKey] === undefined) {
+        entity[EntityRuntimeKey] = createEntityRuntime();
+    }
+    entity[EntityRuntimeKey].binding = binding;
+}
+export function getEntityBinding(source) {
+    const runtime = getEntityRuntime(source);
+    return runtime?.binding ?? null;
+}
+//# sourceMappingURL=binding.js.map

package/dist/binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElE,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,OAAe;IACjE,IAAI,MAAM,CAAC,gBAAgB,CAAC,KAAK,SAAS,EAAE,CAAC;QAC3C,MAAM,CAAC,gBAAgB,CAAC,GAAG,mBAAmB,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,CAAC,gBAAgB,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzC,OAAO,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC;AAClC,CAAC"}

package/dist/clone.d.ts

@@ -0,0 +1,4 @@
+import type { Entity, EntityWithoutRuntime } from '@flighthq/types';
+export declare function cloneEntity<Type extends Entity>(source: Readonly<Type>): Type;
+export declare function stripEntityRuntime<Type extends Entity>(source: Readonly<Type>): EntityWithoutRuntime<Type>;
+//# sourceMappingURL=clone.d.ts.map

package/dist/clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone.d.ts","sourceRoot":"","sources":["../src/clone.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAQpE,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAI7E;AAMD,wBAAgB,kBAAkB,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAI1G"}

package/dist/clone.js

@@ -0,0 +1,20 @@
+import { EntityRuntimeKey } from '@flighthq/types';
+import { createEntity } from './entity';
+// Allocates a new entity by copying the public data fields of the source, with the runtime
+// slot reset to undefined. The clone is a fresh, unbound entity — runtime and binding are
+// intentionally not carried over.
+export function cloneEntity(source) {
+    const copy = { ...source };
+    copy[EntityRuntimeKey] = undefined;
+    return createEntity(copy);
+}
+// Returns a plain object with the EntityRuntimeKey slot removed, ready to pass to a
+// serializer or JSON.stringify. The runtime is explicitly non-serializable; this helper
+// provides the one canonical strip path so each consuming package does not need to know
+// about the slot key.
+export function stripEntityRuntime(source) {
+    const copy = { ...source };
+    delete copy[EntityRuntimeKey];
+    return copy;
+}
+//# sourceMappingURL=clone.js.map

package/dist/clone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone.js","sourceRoot":"","sources":["../src/clone.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,2FAA2F;AAC3F,0FAA0F;AAC1F,kCAAkC;AAClC,MAAM,UAAU,WAAW,CAAsB,MAAsB;IACrE,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,EAAkC,CAAC;IAC3D,IAAI,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC;IACnC,OAAO,YAAY,CAAC,IAAuB,CAAC,CAAC;AAC/C,CAAC;AAED,oFAAoF;AACpF,wFAAwF;AACxF,wFAAwF;AACxF,sBAAsB;AACtB,MAAM,UAAU,kBAAkB,CAAsB,MAAsB;IAC5E,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,EAAkC,CAAC;IAC3D,OAAO,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAC9B,OAAO,IAA6C,CAAC;AACvD,CAAC"}

package/dist/entity.d.ts

@@ -0,0 +1,3 @@
+import type { Entity } from '@flighthq/types';
+export declare function createEntity<Type extends object>(obj?: Type): Type & Entity;
+//# sourceMappingURL=entity.d.ts.map

package/dist/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAG9C,wBAAgB,YAAY,CAAC,IAAI,SAAS,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAK3E"}

package/dist/entity.js

@@ -0,0 +1,9 @@
+import { EntityRuntimeKey } from '@flighthq/types';
+export function createEntity(obj) {
+    if (!obj)
+        obj = {};
+    const entity = obj;
+    entity[EntityRuntimeKey] = undefined;
+    return entity;
+}
+//# sourceMappingURL=entity.js.map

package/dist/entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,UAAU,YAAY,CAAsB,GAAU;IAC1D,IAAI,CAAC,GAAG;QAAE,GAAG,GAAG,EAAU,CAAC;IAC3B,MAAM,MAAM,GAAG,GAAoB,CAAC;IACpC,MAAM,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC;IACrC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/guards.d.ts

@@ -0,0 +1,6 @@
+import type { Entity, EntityRuntime } from '@flighthq/types';
+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;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAI7D,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"}

package/dist/guards.js

@@ -0,0 +1,57 @@
+import { EntityRuntimeKey } from '@flighthq/types';
+// Returns true if entity runtime guards have been enabled via enableEntityRuntimeGuards.
+export function areEntityRuntimeGuardsEnabled() {
+    return _guardsEnabled;
+}
+// Creates a guarded entity that warns when the runtime slot is written directly rather
+// than through ensureEntityRuntime or attachEntityBinding. Only active when guards are
+// enabled via enableEntityRuntimeGuards.
+export function createGuardedEntity(entity) {
+    if (!_guardsEnabled || typeof Proxy === 'undefined')
+        return 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);
+            }
+            target[prop] = value;
+            return true;
+        },
+    });
+}
+// Returns a guarded proxy over an existing EntityRuntime that warns when the binding slot
+// is written outside of attachEntityBinding / detachEntityBinding. Only active when guards
+// are enabled.
+export function createGuardedEntityRuntime(runtime) {
+    if (!_guardsEnabled || typeof Proxy === 'undefined')
+        return 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);
+            }
+            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')
+        return;
+    _guardsEnabled = true;
+}
+let _guardsEnabled = false;
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,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"}

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

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

package/dist/index.js.map

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

package/dist/runtime.d.ts

@@ -0,0 +1,5 @@
+import type { Entity, EntityRuntime } from '@flighthq/types';
+export declare function createEntityRuntime(): EntityRuntime;
+export declare function getEntityRuntime(source: Readonly<Entity>): Readonly<EntityRuntime>;
+export declare function hasEntityRuntime(source: Readonly<Entity>): boolean;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAG7D,wBAAgB,mBAAmB,IAAI,aAAa,CAInD;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,CAElF;AAKD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAElE"}

package/dist/runtime.js

@@ -0,0 +1,16 @@
+import { EntityRuntimeKey } from '@flighthq/types';
+export function createEntityRuntime() {
+    return {
+        binding: null,
+    };
+}
+export function getEntityRuntime(source) {
+    return source[EntityRuntimeKey];
+}
+// Returns true when the entity's runtime slot has been allocated — i.e. the entity has been
+// bound (attachEntityBinding) or otherwise given a runtime. A fresh or cloned entity has no
+// runtime and returns false.
+export function hasEntityRuntime(source) {
+    return source[EntityRuntimeKey] !== undefined;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAwB;IACvD,OAAO,MAAM,CAAC,gBAAgB,CAAE,CAAC;AACnC,CAAC;AAED,4FAA4F;AAC5F,4FAA4F;AAC5F,6BAA6B;AAC7B,MAAM,UAAU,gBAAgB,CAAC,MAAwB;IACvD,OAAO,MAAM,CAAC,gBAAgB,CAAC,KAAK,SAAS,CAAC;AAChD,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flighthq/entity",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Core entity/runtime data model and binding system",
+  "sideEffects": false
+}

package/src/binding.test.ts

@@ -0,0 +1,42 @@
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { attachEntityBinding, getEntityBinding } from './binding';
+import { createEntity } from './entity';
+import { createEntityRuntime, getEntityRuntime } from './runtime';
+
+describe('attachEntityBinding', () => {
+  it('creates a runtime object if none is present', () => {
+    const entity = createEntity();
+    expect(getEntityRuntime(entity)).toBeUndefined();
+    attachEntityBinding(entity, {});
+    expect(getEntityRuntime(entity)).not.toBeUndefined();
+  });
+
+  it('assigns to the binding slot', () => {
+    const entity = createEntity();
+    const binding = {};
+    attachEntityBinding(entity, binding);
+    expect(getEntityRuntime(entity).binding).toStrictEqual(binding);
+  });
+});
+
+describe('getEntityBinding', () => {
+  it('returns null if the entity has no runtime', () => {
+    const entity = createEntity();
+    expect(getEntityBinding(entity)).toBeNull();
+  });
+
+  it('returns null if the binding slot is empty', () => {
+    const entity = createEntity();
+    entity[EntityRuntimeKey] = createEntityRuntime();
+    expect(getEntityBinding(entity)).toBeNull();
+  });
+
+  it('returns the binding slot if set', () => {
+    const entity = createEntity();
+    const runtime = createEntityRuntime();
+    runtime.binding = {};
+    entity[EntityRuntimeKey] = runtime;
+    expect(getEntityBinding(entity)).toStrictEqual(runtime.binding);
+  });
+});

package/src/clone.test.ts

@@ -0,0 +1,82 @@
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { attachEntityBinding } from './binding';
+import { cloneEntity, stripEntityRuntime } from './clone';
+import { createEntity } from './entity';
+import { hasEntityRuntime } from './runtime';
+
+describe('cloneEntity', () => {
+  it('returns a new entity with the same public data fields', () => {
+    const source = createEntity({ x: 1, y: 2 });
+    const clone = cloneEntity(source);
+    expect(clone.x).toBe(1);
+    expect(clone.y).toBe(2);
+  });
+
+  it('resets the runtime slot to undefined on the clone', () => {
+    const source = createEntity();
+    attachEntityBinding(source, {});
+    expect(hasEntityRuntime(source)).toBe(true);
+    const clone = cloneEntity(source);
+    expect(hasEntityRuntime(clone)).toBe(false);
+  });
+
+  it('does not share the runtime between source and clone', () => {
+    const source = createEntity();
+    const clone = cloneEntity(source);
+    expect(clone[EntityRuntimeKey]).toBeUndefined();
+    expect(clone).not.toBe(source);
+  });
+
+  it('returns a new object reference', () => {
+    const source = createEntity();
+    const clone = cloneEntity(source);
+    expect(clone).not.toBe(source);
+  });
+
+  it('clone of a bound entity yields an unbound clone', () => {
+    const source = createEntity({ name: 'test' });
+    attachEntityBinding(source, { hostRef: 42 });
+    const clone = cloneEntity(source);
+    expect(hasEntityRuntime(clone)).toBe(false);
+    expect(clone.name).toBe('test');
+  });
+});
+
+describe('stripEntityRuntime', () => {
+  it('removes the EntityRuntimeKey slot', () => {
+    const entity = createEntity({ x: 10 });
+    const stripped = stripEntityRuntime(entity);
+    expect((stripped as Record<PropertyKey, unknown>)[EntityRuntimeKey]).toBeUndefined();
+  });
+
+  it('retains the public data fields', () => {
+    const entity = createEntity({ x: 10, y: 20 });
+    const stripped = stripEntityRuntime(entity);
+    expect(stripped.x).toBe(10);
+    expect(stripped.y).toBe(20);
+  });
+
+  it('does not mutate the source entity', () => {
+    const entity = createEntity({ x: 10 });
+    stripEntityRuntime(entity);
+    expect(entity[EntityRuntimeKey]).toBeUndefined();
+  });
+
+  it('strips bound entity — binding is not in the output', () => {
+    const entity = createEntity({ label: 'hello' });
+    attachEntityBinding(entity, { nativeRef: true });
+    const stripped = stripEntityRuntime(entity);
+    expect((stripped as Record<PropertyKey, unknown>)[EntityRuntimeKey]).toBeUndefined();
+    expect(stripped.label).toBe('hello');
+  });
+
+  it('round-trips: stripEntityRuntime then createEntity yields a valid unbound entity', () => {
+    const original = createEntity({ value: 99 });
+    attachEntityBinding(original, {});
+    const stripped = stripEntityRuntime(original);
+    const restored = createEntity(stripped);
+    expect(restored.value).toBe(99);
+    expect(hasEntityRuntime(restored)).toBe(false);
+  });
+});

package/src/entity.test.ts

@@ -0,0 +1,15 @@
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { createEntity } from './entity';
+
+describe('createEntity', () => {
+  it('returns an object', () => {
+    const entity = createEntity();
+    expect(entity).not.toBeNull();
+  });
+
+  it('has an undefined runtime', () => {
+    const entity = createEntity();
+    expect(entity[EntityRuntimeKey]).toBeUndefined();
+  });
+});

package/src/guards.test.ts

@@ -0,0 +1,64 @@
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { createEntity } from './entity';
+import {
+  areEntityRuntimeGuardsEnabled,
+  createGuardedEntity,
+  createGuardedEntityRuntime,
+  enableEntityRuntimeGuards,
+} from './guards';
+import { createEntityRuntime } from './runtime';
+
+describe('areEntityRuntimeGuardsEnabled', () => {
+  it('returns false before enableEntityRuntimeGuards is called', () => {
+    // Vitest isolates modules per file, so this starts false in a fresh module import.
+    expect(areEntityRuntimeGuardsEnabled()).toBe(false);
+  });
+});
+
+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);
+  });
+});
+
+describe('createGuardedEntityRuntime', () => {
+  it('returns the runtime unchanged when guards are not enabled', () => {
+    const runtime = createEntityRuntime();
+    const guarded = createGuardedEntityRuntime(runtime);
+    expect(guarded).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);
+  });
+
+  it('createGuardedEntityRuntime returns a proxy when guards are enabled', () => {
+    enableEntityRuntimeGuards();
+    const runtime = createEntityRuntime();
+    const guarded = createGuardedEntityRuntime(runtime);
+    expect(guarded.binding).toBeNull();
+  });
+
+  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();
+  });
+});

package/src/runtime.test.ts

@@ -0,0 +1,41 @@
+import type { EntityRuntime } from '@flighthq/types';
+import { EntityRuntimeKey } from '@flighthq/types';
+
+import { attachEntityBinding } from './binding';
+import { createEntity } from './entity';
+import { createEntityRuntime, getEntityRuntime, hasEntityRuntime } from './runtime';
+
+describe('createEntityRuntime', () => {
+  it('returns an object', () => {
+    const runtime = createEntityRuntime();
+    expect(runtime).not.toBeNull();
+  });
+
+  it('has a null api slot', () => {
+    const runtime = createEntityRuntime();
+    expect(runtime.binding).toBeNull();
+  });
+});
+
+describe('getEntityRuntime', () => {
+  it('returns the runtime object', () => {
+    const entity = createEntity();
+    expect(getEntityRuntime(entity)).toBeUndefined();
+    const runtime = {} as EntityRuntime;
+    entity[EntityRuntimeKey] = runtime;
+    expect(getEntityRuntime(entity)).toStrictEqual(runtime);
+  });
+});
+
+describe('hasEntityRuntime', () => {
+  it('returns false for a fresh entity', () => {
+    const entity = createEntity();
+    expect(hasEntityRuntime(entity)).toBe(false);
+  });
+
+  it('returns true after a binding is attached', () => {
+    const entity = createEntity();
+    attachEntityBinding(entity, {});
+    expect(hasEntityRuntime(entity)).toBe(true);
+  });
+});