@flighthq/entity 0.5.1-next.731.0ae0aa4 → 0.5.1-next.799.62ef0c7

package/README.md

@@ -13,5 +13,5 @@ Import the supported application-facing API from `@flighthq/entity`. The `@fligh
 This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
 
 - [Flight project](https://github.com/flighthq/flight)
-- [Source for @flighthq/entity@0.5.1-next.731.0ae0aa4](https://github.com/flighthq/flight/tree/0ae0aa49d8251d23b546f64bc242f3ad59a98dcb/packages/entity)
-- [License](https://github.com/flighthq/flight/blob/0ae0aa49d8251d23b546f64bc242f3ad59a98dcb/LICENSE.md)
+- [Source for @flighthq/entity@0.5.1-next.799.62ef0c7](https://github.com/flighthq/flight/tree/62ef0c74f09f24177aac3695b2487b2d743d4fe6/packages/entity)
+- [License](https://github.com/flighthq/flight/blob/62ef0c74f09f24177aac3695b2487b2d743d4fe6/LICENSE.md)

package/dist/contract.d.ts

@@ -3,6 +3,7 @@ export * from './clone';
 export * from './entity';
 export * from './enableEntityRuntimeGuards';
 export * from './entityUid';
+export * from './explainEntityRuntimeWrite';
 export * from './guards';
 export * from './host';
 export * from './runtime';

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,6BAA6B,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,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,aAAa,CAAC;AAC5B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC"}

package/dist/contract.js

@@ -3,6 +3,7 @@ export * from './clone';
 export * from './entity';
 export * from './enableEntityRuntimeGuards';
 export * from './entityUid';
+export * from './explainEntityRuntimeWrite';
 export * from './guards';
 export * from './host';
 export * from './runtime';

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,6BAA6B,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,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,aAAa,CAAC;AAC5B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC"}

package/dist/enableEntityRuntimeGuards.d.ts

@@ -1,3 +1,4 @@
+import type { EntityRuntimeWriteGuard } from '@flighthq/types/contract';
 export declare function disableEntityRuntimeGuards(): void;
-export declare function enableEntityRuntimeGuards(): void;
+export declare function enableEntityRuntimeGuards(report: EntityRuntimeWriteGuard): void;
 //# sourceMappingURL=enableEntityRuntimeGuards.d.ts.map

package/dist/enableEntityRuntimeGuards.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"enableEntityRuntimeGuards.d.ts","sourceRoot":"","sources":["../src/enableEntityRuntimeGuards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAKxE,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD;AAYD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAG/E"}

package/dist/enableEntityRuntimeGuards.js

@@ -1,5 +1,3 @@
-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() {
@@ -7,27 +5,17 @@ export function disableEntityRuntimeGuards() {
     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 attachEntityBinding is reported,
-// making "the write landed on the wrong entity" and raw-slot-poke bugs visible early. The write is still
+// EntityRuntime's binding slot — that bypasses attachEntityBinding is reported to `report`, 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() {
+// The reporter is the CALLER's. @flighthq/entity is a core package and owns no sink: it does not reach
+// for a logger, a console, or any other ambient singleton, so nothing about where diagnostics go is
+// decided here. Pass explainEntityRuntimeWrite's result to whatever the app already logs through.
+// Turning the proxies on and installing the reporter is one act, which is why this exists rather than
+// leaving callers to pair setEntityRuntimeGuardMode with setEntityRuntimeWriteGuard. Idempotent.
+export function enableEntityRuntimeGuards(report) {
     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 attachEntityBinding, which allocates the slot for you; the write was allowed, but bypassing it is how a runtime ends up on the wrong entity.",
-    }, 'entity');
+    setEntityRuntimeWriteGuard(report);
 }
 //# sourceMappingURL=enableEntityRuntimeGuards.js.map

package/dist/enableEntityRuntimeGuards.js.map

@@ -1 +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,gFAAgF;AAChF,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,iMAAiM;KACpM,EACD,QAAQ,CACT,CAAC;AACJ,CAAC"}
+{"version":3,"file":"enableEntityRuntimeGuards.js","sourceRoot":"","sources":["../src/enableEntityRuntimeGuards.ts"],"names":[],"mappings":"AAEA,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,mGAAmG;AACnG,kGAAkG;AAClG,kDAAkD;AAClD,EAAE;AACF,uGAAuG;AACvG,oGAAoG;AACpG,kGAAkG;AAClG,sGAAsG;AACtG,iGAAiG;AACjG,MAAM,UAAU,yBAAyB,CAAC,MAA+B;IACvE,yBAAyB,CAAC,IAAI,CAAC,CAAC;IAChC,0BAA0B,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC"}

package/dist/explainEntityRuntimeWrite.d.ts

@@ -0,0 +1,3 @@
+import type { EntityRuntimeWriteExplanation, EntityRuntimeWriteSlot } from '@flighthq/types/contract';
+export declare function explainEntityRuntimeWrite(slot: EntityRuntimeWriteSlot): EntityRuntimeWriteExplanation;
+//# sourceMappingURL=explainEntityRuntimeWrite.d.ts.map

package/dist/explainEntityRuntimeWrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainEntityRuntimeWrite.d.ts","sourceRoot":"","sources":["../src/explainEntityRuntimeWrite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAMtG,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,GAAG,6BAA6B,CAerG"}

package/dist/explainEntityRuntimeWrite.js

@@ -0,0 +1,19 @@
+// Describes what a guarded direct write means, as plain data. The guard seam reports only which slot was
+// written; this turns that into the remedy, so a caller's reporter can phrase a warning without core
+// owning a message format or a logger. Separately importable, so a build that never diagnoses these
+// writes never carries the text.
+export function explainEntityRuntimeWrite(slot) {
+    if (slot === 'binding-slot') {
+        return {
+            message: 'EntityRuntime.binding was written directly. The write was allowed but is not tracked, so the binding and the runtime can disagree.',
+            slot,
+            useInstead: ['attachEntityBinding', 'detachEntityBinding'],
+        };
+    }
+    return {
+        message: "An entity's runtime slot was written directly. The write was allowed, but bypassing the helper is how a runtime ends up on the wrong entity.",
+        slot,
+        useInstead: ['attachEntityBinding'],
+    };
+}
+//# sourceMappingURL=explainEntityRuntimeWrite.js.map

package/dist/explainEntityRuntimeWrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainEntityRuntimeWrite.js","sourceRoot":"","sources":["../src/explainEntityRuntimeWrite.ts"],"names":[],"mappings":"AAEA,yGAAyG;AACzG,qGAAqG;AACrG,oGAAoG;AACpG,iCAAiC;AACjC,MAAM,UAAU,yBAAyB,CAAC,IAA4B;IACpE,IAAI,IAAI,KAAK,cAAc,EAAE,CAAC;QAC5B,OAAO;YACL,OAAO,EACL,oIAAoI;YACtI,IAAI;YACJ,UAAU,EAAE,CAAC,qBAAqB,EAAE,qBAAqB,CAAC;SAC3D,CAAC;IACJ,CAAC;IACD,OAAO;QACL,OAAO,EACL,8IAA8I;QAChJ,IAAI;QACJ,UAAU,EAAE,CAAC,qBAAqB,CAAC;KACpC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/entity",
-  "version": "0.5.1-next.731.0ae0aa4",
+  "version": "0.5.1-next.799.62ef0c7",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,7 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/log": "0.5.1-next.731.0ae0aa4",
-    "@flighthq/types": "0.5.1-next.731.0ae0aa4"
+    "@flighthq/types": "0.5.1-next.799.62ef0c7"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/enableEntityRuntimeGuards.test.ts

@@ -1,5 +1,4 @@
-import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
-import type { LogEntry } from '@flighthq/types/contract';
+import type { EntityRuntimeWriteSlot } from '@flighthq/types/contract';
 import { EntityRuntimeKey } from '@flighthq/types/contract';
 
 import { disableEntityRuntimeGuards, enableEntityRuntimeGuards } from './enableEntityRuntimeGuards';
@@ -7,69 +6,47 @@ 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);
+// Every case runs the write under a reporter that records the slot, so what is asserted is what the
+// caller's reporter actually received — not that some sink somewhere was touched.
+function recordSlots(write: () => void): readonly EntityRuntimeWriteSlot[] {
+  const slots: EntityRuntimeWriteSlot[] = [];
+  enableEntityRuntimeGuards((slot) => slots.push(slot));
   try {
-    run();
-    return getMemoryLogSinkEntries(sink);
+    write();
   } finally {
-    removeLogSink(sink.sink);
+    disableEntityRuntimeGuards();
   }
-}
-
-function messageOf(entry: Readonly<LogEntry>): string {
-  const data = entry.data;
-  return typeof data === 'string' ? data : String(data.message);
+  return slots;
 }
 
 describe('disableEntityRuntimeGuards', () => {
   it('uninstalls both the proxies and the reporter', () => {
-    const entries = captureLog(() => {
-      enableEntityRuntimeGuards();
-      disableEntityRuntimeGuards();
-      createGuardedEntity(createEntity())[EntityRuntimeKey] = undefined;
-    });
-    expect(entries.length).toBe(0);
+    const slots: EntityRuntimeWriteSlot[] = [];
+    enableEntityRuntimeGuards((slot) => slots.push(slot));
+    disableEntityRuntimeGuards();
+    createGuardedEntity(createEntity())[EntityRuntimeKey] = undefined;
+    expect(slots).toEqual([]);
     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);
-    // Names a function that actually exists: the point of the warning is that the caller can act on it.
-    expect(messageOf(entries[0])).toContain('attachEntityBinding');
+  it('REPORTS a direct runtime-slot write to the caller-supplied reporter', () => {
+    expect(recordSlots(() => (createGuardedEntity(createEntity())[EntityRuntimeKey] = undefined))).toEqual([
+      'runtime-slot',
+    ]);
   });
 
-  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');
-    expect(messageOf(entries[0])).toContain('detachEntityBinding');
+  it('REPORTS a direct binding-slot write separately', () => {
+    expect(recordSlots(() => (createGuardedEntityRuntime(createEntityRuntime()).binding = null))).toEqual([
+      'binding-slot',
+    ]);
   });
 
   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);
+    const slots: EntityRuntimeWriteSlot[] = [];
+    createGuardedEntity(createEntity())[EntityRuntimeKey] = undefined;
+    expect(slots).toEqual([]);
     expect(areEntityRuntimeGuardsEnabled()).toBe(false);
   });
 });

package/src/explainEntityRuntimeWrite.test.ts

@@ -0,0 +1,21 @@
+import { explainEntityRuntimeWrite } from './explainEntityRuntimeWrite';
+
+describe('explainEntityRuntimeWrite', () => {
+  it('names both binding helpers for a binding-slot write', () => {
+    const explanation = explainEntityRuntimeWrite('binding-slot');
+    expect(explanation.slot).toBe('binding-slot');
+    expect(explanation.useInstead).toEqual(['attachEntityBinding', 'detachEntityBinding']);
+  });
+
+  it('names the allocating helper for a runtime-slot write', () => {
+    const explanation = explainEntityRuntimeWrite('runtime-slot');
+    expect(explanation.slot).toBe('runtime-slot');
+    expect(explanation.useInstead).toEqual(['attachEntityBinding']);
+  });
+
+  it('distinguishes the two slots by message, not only by name', () => {
+    expect(explainEntityRuntimeWrite('binding-slot').message).not.toBe(
+      explainEntityRuntimeWrite('runtime-slot').message,
+    );
+  });
+});